IMP logo
IMP Manual  for IMP version 2.6.1
biosystem.md
1 Applying %IMP to a new biological system {#biosystem}
2 ========================================
3 
4 We have already applied %IMP to solve the structures of many novel biological
5 systems, listed on the [biological systems page](https://integrativemodeling.org/systems/).
6 Each system on that page includes all of the files needed to reproduce the
7 results in the accompanying publication. For example, the list includes the
8 [modeling example from earlier in this manual](@ref rnapolii_stalk), as well
9 as [modeling of the Nup84 subcomplex of the Nuclear Pore Complex](https://salilab.org/nup84). Each system is periodically rerun with the latest version of %IMP
10 to make sure that it still works correctly.
11 
12 To apply %IMP to a new biological system, you are welcome to use one of the
13 existing systems, such as the [Nup84 model](https://salilab.org/nup84),
14 as your template - or you can write from scratch using the basic %IMP classes
15 and/or the IMP::pmi higher level interface. In either case, we strongly
16 recommend that you manage your application as a GitHub repository so that
17  - others can reproduce your published work
18  - changes to the protocol can be documented or rolled back if necessary
19  - your system can be added to [our list](https://integrativemodeling.org/systems/), so that we can test newer versions of %IMP to make sure we don't break something
20 
21 We recommend the following contents for your repository (see the
22 [Nup84 repository](https://github.com/integrativemodeling/nup84)
23 for an example):
24 
25  - subdirectories containing your modeling protocol (generally one or more
26  Python scripts), input files (e.g. PDB files, EM density maps, lists of
27  crosslinks), and outputs (where possible, due to size; it may not be feasible
28  to upload all of your output models, for example, but only cluster
29  representatives).
30  - a top-level `%README.md` file describing the system and explaining how to
31  run the protocol.
32  - a `test` directory containing one or more Python scripts with names starting
33  with `test`. It should be
34  possible to run these scripts without any "special" setup (e.g. they should
35  not require any input arguments or environment variables, or use
36  hard-coded paths). These scripts should run as much of your modeling
37  protocol as possible, and ideally test the results (e.g. by comparing models
38  against 'known good' clusters). Each script should simply exit with a
39  non-zero exit code (e.g. by raising an exception) if something failed; one
40  easy way to do this nicely is to use Python's
41  [unittest](https://docs.python.org/2/library/unittest.html) module. The
42  tests should run in a "reasonable" amount of time (no more than 48 hours)
43  on a single processor. If this is not enough time to run your entire
44  protocol, run only a representative subset
45  (e.g. the Nup84 modeling test passes a `--test` option to the modeling
46  script, which has it perform fewer iterations of sampling).
47  - to add your system to [our list](https://integrativemodeling.org/systems/)
48  it will also need a `metadata` subdirectory (also
49  [contact us](https://integrativemodeling.org/contact.html) to let us know
50  about it).
51  This should contain two files:
52  - `thumb.png`: a small image used to represent your system on the page.
53  - `metadata.yaml`: a file in [YAML](http://yaml.org/) format specifying
54  (see also the [Nup84 example](https://github.com/integrativemodeling/nup84/blob/master/metadata/metadata.yaml)):
55  - `title`: a short descriptive name for your system
56  - `tags`: a list of tags to group your system with others that use
57  similar methods or input data
58  - `pmid`: the PubMed ID of the accompanying publication
59  - `prereqs`: a list of any non-standard packages that are needed
60  (in addition to %IMP and Python's standard library) to run the scripts
61  - `runtime`: upper limit to the time the tests will take to run
62  - `build`: which type of %IMP build to run the tests with
63  (`release`, `fast` or `debug`); `release` is generally recommended