Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions docs/Troubleshooting/install_trbl.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
We are not aware of how the installation might have failed on linux. Please submit an
<a href="https://github.com/bforsbe/OccuPy/issues">issue</a>, describing your system and observations.

## The GUI windows looks too big/small/...
## The GUI window looks too big/small/...

On some (e.g. 4K) screens, the high resolution causes graphical elements to be re-scaled. OccuPy knows about this
and does its best to get it right, but we have not been able to test on a wide range of screen sizes and resolutions.
Expand Down Expand Up @@ -91,7 +91,7 @@ Let's first confirm that it was in fact installed.

1. In the main menu search bar, type "powershell", and open a text-based interface to your system.
2. Type `py -m pip show occupy` and hit enter. If you see details regarding occupy, then we're good. If not, try
writing out "python" instan of just "py": `python -m pip show occupy`.
writing out "python" instead of just "py": `python -m pip show occupy`.
3. If you still don't see details like version and location, then occupy probably wasn't installed properly.
You need to try to install it according to the install procedures,
and <a href="https://form.jotform.com/223012138013033" target="_blank" rel="noopener noreferrer">ask for help</a>
Expand All @@ -109,7 +109,7 @@ Let's first confirm that it was in fact installed.
version and location, then occupy probably wasn't installed properly. If you used a virtual environment when
installing, make sure to activate it like you did before, and try again.

If OccuPy you managed to confirm that OccuPy was installed, Pip may have installed OccuPy in a location that is
If you managed to confirm that OccuPy was installed, Pip may have installed OccuPy in a location that is
not universally known to your system.
You can either tell your system where to look when searching for installed applications, or
create a shortcut to it that you can find easily.
Expand All @@ -134,7 +134,7 @@ In either case, we need to find where occupy was installed.

=== "On Mac"

1. In a terminal where pip is avaialble, call ```pip show occupy```. The reported location is a good indication
1. In a terminal where pip is available, call ```pip show occupy```. The reported location is a good indication
of where occupy was installed. If the locaton is ```/home/bjornf/.local/lib/python3.8/site-packages```, then the
location of the program is likely ```/home/bjornf/.local/bin```

Expand All @@ -143,12 +143,12 @@ In either case, we need to find where occupy was installed.

3. The PATH variable is a colon-separated list. Add the ```occupy_gui``` path as new entry in this list.

4. If you do mot have the access rights to to this system-wide, you can add the following to your session
4. If you do not have the access rights to do this system-wide, you can add the following to your session
startup file: ```export PATH=$PATH:</path/to/occupy/program>```

=== "On Linux (ubuntu)"

1. In a terminal where pip is avaialble, call ```pip show occupy```. The reported location is a good indication
1. In a terminal where pip is available, call ```pip show occupy```. The reported location is a good indication
of where occupy was installed. If the locaton is ```/home/bjornf/.local/lib/python3.8/site-packages```, then the
location of the program is likely ```/home/bjornf/.local/bin```

Expand All @@ -157,5 +157,5 @@ In either case, we need to find where occupy was installed.

3. The PATH variable is a colon-separated list. Add the ```occupy_gui``` path as new entry in this list.

4. If you do mot have the access rights to to this system-wide, you can add the following to your session
startup file: ```export PATH=$PATH:</path/to/occupy/program>```
4. If you do not have the access rights to do this system-wide, you can add the following to your session
startup file: ```export PATH=$PATH:</path/to/occupy/program>```
17 changes: 8 additions & 9 deletions docs/Troubleshooting/other_trbl.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,8 @@ For extensive information regarding input options, see the GUI overview tutorial
1. The modification is effected by the power you choose, where values larger than 1 mean to modify. Larger
values mean to modify more, and typically values between 2 and 10 are useful. Try increasing it.
2. Check your solvent model (tab next to output log). The modification is suppressed if the estimated solvent model
is very wide, which decreases confidence in partial occupancies. If
3.
there isn't enough solvent for the fitting of the solvent model, it will typically be too wide and prevent
is very wide, which decreases confidence in partial occupancies.
3. If there isn't enough solvent for the fitting of the solvent model, it will typically be too wide and prevent
modification of lower-scale components. You can check this by using the `--plot` option and inspecting the output.
You can also use `--solvent-def <mask.mrc>` where the mask is a conventional solvent-mask. This will allow these
regions to be omitted during solvent fitting. _This mask does not need to be perfect, and does not limit the
Expand All @@ -25,15 +24,15 @@ For extensive information regarding input options, see the GUI overview tutorial
1. Well you might have a rock of a complex.
2. If you set the value of `--tau/-t` manually low, then this is the reason. If it got auto-calculated low, you can
increase it, but this is a bad idea. It is rather better to increase the `--kernel` so that the value of tau
is automatically increased. You may also waent to increase `--lowpass/-lp` ot increase the number of sampled
pixel `nv`. You can see what paramters were calculated and used by checking the output log file or using the
is automatically increased. You may also want to increase `--lowpass/-lp` ot increase the number of sampled
pixels `nv`. You can see what parameters were calculated and used by checking the output log file or using the
`--verbose` option. Increasing the kernel size and/or lowpass setting permits more confident sampling of the local
scale, but does increase the granularity. Usually a kernel size of 5 or 7 is adequate, with nv-values in the
range 30-100. Low-pass defaults to 8 or 3*pixel-size, which ever is larger, but depending on resolution and
range 30-100. Low-pass defaults to 8 or 3*pixel-size, whichever is larger, but depending on resolution and
pixel-size this may be adjusted depending on the sought granularity.
3. OccuPy puts everything on a scale based on what it estimates as "full" through a non-exhaustive search. It
is non-exhaustive because it's much faster. If the "full" scale is under-estimated, lots of regions will be
"over-full", i.e. over-estimated as full. YOu can reduce the `--tile-size ` from its default value 12 to reduce
"over-full", i.e. over-estimated as full. You can reduce the `--tile-size ` from its default value 12 to reduce
the area of what defines "full" scale, which will narrow the definition and in general increase the value of full
occupancy, thus stretching the range of the estimated scale. For high-resolution maps, a very small tile-size
makes the local scale approximate the mass of individual atoms.
Expand All @@ -42,7 +41,7 @@ For extensive information regarding input options, see the GUI overview tutorial
confidence by using `--hedge-confidence <val>`, where `<val>` is a power, meaning that higher values hedge
more. 10 is a reasonable value to try.
5. Another possible reason for the confidence being over-estimated is that the solvent model mean and/or variance is
under-estimated. A typical reason for this is that the solvent has been flattened, such that the solvent is not
under-estimated. A typical reason for this is that the solvent has been flattened, such that the solvent is no longer
gaussian. OccuPy was not designed for this type of reconstruction, since such flattening is typically enforced
using a mask which has thus already delineated solvent vs non-solvent.
6. If the map is not solvent-flattened, and confidence-hedging does not alleviate solvent-amplification surrounding
Expand All @@ -56,7 +55,7 @@ is not possible to trivially separate these factors, the current approach to est
lower resolution is to low-pass filter the input before estimating the local scale. This is turned on
when amplifying or attenuating the map, to minimize over-amplification of low-scale components that are simply low
resolution. If one is just estimating scale, but still wants to reduce resolution-dependent effects, the low-pass
filtration before scale-estimation can be used. It should then be combined a low-pass filter
filtration before scale-estimation can be used. It should then be combined with a low-pass filter
to specify the worst resolution among the components for which occupancy is to
be estimated. For membrane proteins, see [here](#my-membrane-or-detergent-looks-funny).

Expand Down
24 changes: 12 additions & 12 deletions docs/Tutorials/case/est_occ.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,16 +19,16 @@ The following steps highlight factors influencing this, and how to make the nece

## 1. First pass estimate
1. Open the input map.
2. Make sure "occupancy" (just below the modification options is enabled, and estimate the scale.
2. Make sure "occupancy" (just below the modification options) is enabled, and estimate the scale.
3. Click the button "Launch ChimeraX" to view the output.

---

## 2. Sanity check
1. Check that the output log does not show any warnings (or errors).
2. Check the "Conf." tab in the viewer. It should be white where there is "stuff", and black where there is solvent.
If this si not the case, your solvent model might be bad. This is not an issue for occupancy estimation, but it
will be if you want to modify later. If ypu just want to estimate occupancy, go to step 3. Otherwise, check the
If this is not the case, your solvent model might be incorrect. This is not an issue for occupancy estimation, but it
will be if you want to modify later. If you just want to estimate occupancy, go to step 3. Otherwise, check the
solvent model on the tab next to the output log. The green parabola should fit the histogram solvent peak near 0
quite well and drop faster than the histogram. If not, you may need to increase the input lowpass cutoff in the
kernel settings, or even use a solvent definition. There is a dedicated tutorial for this, that you should do
Expand Down Expand Up @@ -60,9 +60,9 @@ correlation, so that the local occupancy is averaged. If your **input map**...
---

### 3.2 The Kernel radius and size
These define the region around each pixel where OccuPy determines the local scale. That is, the define what "local"
These define the region around each pixel where OccuPy determines the local scale. That is, they define what "local"
means. The kernel size is the maximum box dimension, and the radius is that of a spherical mask placed at the center
of that box. The kernel is determined as the intersection of these. the number of voxels in this intersection is
of that box. The kernel is determined as the intersection of these. The number of voxels in this intersection is
shown as the number of samples.

<div class="admonition tip">
Expand Down Expand Up @@ -98,8 +98,8 @@ unless you have good reason to do so. **Always report the kernel settings**
Look at the "Scale" tab of the viewer. In your scale estimate...

1. is homogeneous and nearly all white, then you might have a very homogeneous occupancy. If you want to push the
relative occupancy into a range where you might tell components apart, try increasing the tau percentile an
re-estimate the scale. **This is no longer a good approximation of absolute occupancy**
relative occupancy into a range where you might tell components apart, try increasing the tau percentile and
re-estimate the scale. **This is no longer a good approximation of absolute occupancy.**
2. is only white for a very small region that does not correspond to what you would expect to be at full occupancy,
try reducing the tau percentile. It might also be better to adjust the tile-size as we will soon discuss, and use
the theoretically derived value for tau.
Expand All @@ -108,7 +108,7 @@ Look at the "Scale" tab of the viewer. In your scale estimate...

### 3.4 Tile size
OccuPy normalizes the estimated scale against a region of the map where it in some sense finds maximal contrast. The
size of this region defines the size of the "full occupancy" region. This region can be chosen smaller than you
size of this region defines the size of the "full occupancy" region. This region can be chosen smaller than your
full-occupancy component, but if you make it too small then variations in atomic mass might start to affect the
estimate.

Expand All @@ -119,7 +119,7 @@ Increasing the tile size will reduce the influence of high local mass, and vice
Setting the tile-size too large will cause systematic over-estimation of local scale.
</p>
</div>
Look at the "Scale" tab of the viewer. In your scale estimate...
Look at the "Scale" tab of the viewer. If your scale estimate...

1. is only white for a very small region that does not correspond to what you would expect to be at full occupancy,
try increasing the tile-size.
Expand All @@ -136,7 +136,7 @@ exaggerated occupancy, effectively over-compensated. This can be made evident by
2. Select the "Amplify" tab under modification options. Enable it and set the power to 30.
3. Click "Modify Map"
4. Click "Launch chimeraX", hide the input map and show the modified map. If regions colored by lower scale appear
at lower threshold values than regions at high scale, then the occupancy appears to have been under-estimated. WE
at lower threshold values than regions at high scale, then the occupancy appears to have been under-estimated. We
are working on a way to automate this feedback cycle to get a more accurate occupancy estimate, but for now it
might be prudent to alter the scale kernel settings as described above to better estimate the occupancy.

Expand All @@ -152,14 +152,14 @@ However, one may want to redefine zero occupancy to coincide with the noise dist
expected to display solvent characteristics, especially when noise is high or occupancy is low. Since version 0.1.11,
OccuPy implements a noise-level recalibration option, which takes this into account. **But this is not a one-stop
solution to improve estimation in a high noise setting**, since it demands an accurate solvent model, which may be
difficult precisely in this circumstance.
difficult to determine precisely in this circumstance.

Noise-level recalibration is accessible in the gui under "Optional/extra options", or on the command flag by adding
the flag "--nlrc". Make sure to evaluate the solvent model and confidence estimate before relying on this option.

## 6. Final notes
1. Because a reduced tile-size emphasizes variations in mass even when occupancy is the same, a much reduced tile
size is potentially useful to estimate relative mass or occupancy when the relative mass is known. There are
size is potentially useful to estimate relative mass, or occupancy when the relative mass is known. There are
however better methods available for this purpose, which we recommend for accurate estimation. OccuPy simply
exposes these methods where they might be relevant for fast and highly resolved estimation in the absence of
ground-truth mass.
Expand Down
Loading