diff --git a/docs/Troubleshooting/install_trbl.md b/docs/Troubleshooting/install_trbl.md index 2e6b708..311cda5 100644 --- a/docs/Troubleshooting/install_trbl.md +++ b/docs/Troubleshooting/install_trbl.md @@ -32,7 +32,7 @@ We are not aware of how the installation might have failed on linux. Please submit an issue, 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. @@ -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 ask for help @@ -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. @@ -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``` @@ -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:``` === "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``` @@ -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:``` \ No newline at end of file + 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:``` diff --git a/docs/Troubleshooting/other_trbl.md b/docs/Troubleshooting/other_trbl.md index 4b69326..bbdbd18 100644 --- a/docs/Troubleshooting/other_trbl.md +++ b/docs/Troubleshooting/other_trbl.md @@ -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 ` 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 @@ -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. @@ -42,7 +41,7 @@ For extensive information regarding input options, see the GUI overview tutorial confidence by using `--hedge-confidence `, where `` 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 @@ -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). diff --git a/docs/Tutorials/case/est_occ.md b/docs/Tutorials/case/est_occ.md index ad18e9b..e12037e 100644 --- a/docs/Tutorials/case/est_occ.md +++ b/docs/Tutorials/case/est_occ.md @@ -19,7 +19,7 @@ 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. --- @@ -27,8 +27,8 @@ The following steps highlight factors influencing this, and how to make the nece ## 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 @@ -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.
@@ -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. @@ -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. @@ -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.

-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. @@ -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. @@ -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. diff --git a/docs/Tutorials/case/est_res.md b/docs/Tutorials/case/est_res.md index 993ecb0..60d91bd 100644 --- a/docs/Tutorials/case/est_res.md +++ b/docs/Tutorials/case/est_res.md @@ -41,11 +41,11 @@ score that tells you how well resolved each region is, compared to the best reso ## 3. Evaluate Kernel settings Strong scatterers, variations in resolution, or any of a number of other factors may cause strong contrast. This -means that the signal-to-noise ratio (SNR) is higher, which according to typical cryo-EM estimates more confidence in +means that the signal-to-noise ratio (SNR) is higher, which according to typical cryo-EM estimates also means more confidence in the estimated resolution, but not necessarily higher resolution. OccuPy evaluates contrast, which will be in proportion to SNR, which is thus not ideal for estimating resolution. It is thus prudent to be cautious, but OccuPy was -built to be robust to outliers so with caution everything should be fine. Some settings may need be adjusted, nearly -identically to that described in the tuorial to estimate occupancy. When you explore settings to increase the +built to be robust to outliers so with caution everything should be fine. Some settings may need to be adjusted, nearly +identically to that described in the tutorial to estimate occupancy. When you explore settings to increase the utility (and possibly also the fidelity) of the resolution estimate, note that this creates confirmation bias in the results based on your expectations. **Always report the kernel settings** used, which are documented in the full GUI log, or through command line by using `--verbose`. @@ -63,9 +63,9 @@ The input lowpass is inconsequential for the resolution estimation. --- ### 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.
@@ -89,7 +89,7 @@ Look at the "Scale" tab of the Occupy viewer. If your scale estimate... To reduce the influence of voxel-value outliers in the scale estimate, some voxel values are always "rejected". The tau percentile defines how many sample values should be rejected. The value of tau is optimally calculated based on your kernel settings (to reduce the probability of over- and under-estimating the scale), so you should not change it -unless you have good reason to do so. **Always report the kernel settings** +unless you have good reason to do so. **Always report the kernel settings.**

Gist

@@ -102,7 +102,7 @@ Tau is automatically calculated to minimize both over- and under-estimation. 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 resolution. If you want to push the - relative resolution into a range where you might tell components apart, try increasing the tau percentile an + relative resolution into a range where you might tell components apart, try increasing the tau percentile and re-estimate the scale. 2. is only white for a very small region that does not correspond to what you would expect to be at "best resolution", try reducing the tau percentile. It might also be better to adjust the tile-size as we will soon discuss, and use @@ -110,7 +110,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 "best resolution" region. This region can be chosen smaller than you +size of this region defines the size of the "best resolution" region. This region can be chosen smaller than your "best-resolution component", but if you make it too small then variations in atomic mass might start to affect the estimate. @@ -139,15 +139,15 @@ However, one may want to redefine zero scale to coincide with the noise distribu expected to display solvent characteristics, especially when noise is high or resolution 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 +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 +Noise-level recalibration is accessible in the gui under "Optional/extra options", or on the command-line by adding the flag "--nlrc". Make sure to evaluate the solvent model and confidence estimate before relying on this option. --- ## 5. Final notes 1. Because a reduced tile-size emphasizes variations in mass even when resolution is the same, a much reduced tile - size is potentially useful to estimate relative mass or occupancy when the relative mass is known, but for + size is potentially useful to estimate relative mass, or occupancy when the relative mass is known, but for resolution estimation it does not make much sense to reduce it too far. diff --git a/docs/Tutorials/case/modification.md b/docs/Tutorials/case/modification.md index 5621dac..1871ed1 100644 --- a/docs/Tutorials/case/modification.md +++ b/docs/Tutorials/case/modification.md @@ -3,7 +3,7 @@

You need an occupancy estimate

-Please conduct the tutorial to estimate occupancy before this toturial. +Please conduct the tutorial to estimate occupancy before this tutorial. You will use the same parameters to modify as accurately as possible

@@ -61,7 +61,7 @@ maps. The effect of multiple modification types are not additive, i.e. they are === "Amplify" - Amplification will effectively make low-occupancy components higher. The output map scale will be mapped by a + Amplification will effectively make low-occupancy components higher. The output map scale will be mapped by an inverse power-scaling, which the user specifies. A power of 1 thus means that the output scale is the same as the input, which would leave the output map identical to the input. Higher values signify stronger amplification, and values in the range 2-5 are typically useful. Higher values approach equalization, which emulates full @@ -108,7 +108,7 @@ maps. The effect of multiple modification types are not additive, i.e. they are 1. Click the selected modification type tab under "Modification options", and enable it. 2. Increase the power of the modification to a value above 1. This will alter - the "plot" tab of the viewer. This shows how the output map scale will depend on the estimated (input) scale. - It is useful to look at this tab while changing the parameters to get a sense of sensitive the modification is + It is useful to look at this tab while changing the parameters to get a sense of how sensitive the modification is to changing the modification settings. - the "preview" tab of the viewer. This will show a rough preview of what the output will be. It is not as accurate, and does not consider the confidence map. It will therefore look fairly noisy. It is very useful to diff --git a/docs/Tutorials/case/soldef.md b/docs/Tutorials/case/soldef.md index 9692e73..13f7791 100644 --- a/docs/Tutorials/case/soldef.md +++ b/docs/Tutorials/case/soldef.md @@ -11,8 +11,8 @@ Please read the GUI overview and conduct the intro tutorial first.

Be lazy

-The solvent model is only used for map modification and solvent suppression, so if you are not doing any of these, e. -g. if you just need to estimate the scale, you need not do this tutorial. +The solvent model is only used for map modification and solvent suppression, so if you are not doing any of these, e.g. +if you just need to estimate the scale, you need not do this tutorial.

@@ -23,7 +23,7 @@ In some cases, the solvent peak is not dominant in the input map histogram. Comm 3. reconstructions of partial regions like viral capsids, where little to no solvent is included In these cases, OccuPy can make use of a solvent mask, that instructs it where to look for the solvent peak. However, it -is **not used a mask for the modification or output**. There are benefits to this, like being able to find something +is **not used as a mask for the modification or output**. There are benefits to this, like being able to find something significant outside your mask and amplifying or attenuating it as well. --- @@ -34,7 +34,7 @@ This is the simple approach, and if it works satisfactorily, use it. 1. Open the input map and estimate the scale. 2. Inspect the "Solvent model" tab next to the output log. 3. Increase the input lowpass and estimate the scale again, and note if the solvent model estimation improves. -4. Click the "Conf." tab of the viewer and inspect is OccuPy can adequately tell low-scale stuff from solvent. +4. Click the "Conf." tab of the viewer and inspect if OccuPy can adequately tell low-scale stuff from solvent. --- @@ -49,8 +49,8 @@ size as you input map. --- ## 3. Generate a solvent definition in the GUI -The scale is estimated independently form the solvent model, and can be thresholded or binarized to provide a -solvent defintion. +The scale is estimated independently from the solvent model, and can be thresholded or binarized to provide a +solvent definition. 1. Make sure the appropriate input map is open and selected 2. Estimate the scale. @@ -68,7 +68,7 @@ To evaluate a solvent definition, we inspect the solvent model and resulting con 1. Make sure the appropriate input map is open and selected, then estimate the scale. 2. Inspect the "Solvent model" tab next to the output log. The green parabola is fitted to the masked data histogram in black, whereas the original data histogram is shown in grey. -3. Click the "Conf." tab of the viewer and inspect is OccuPy can adequately tell low-scale stuff from solvent. +3. Click the "Conf." tab of the viewer and inspect if OccuPy can adequately tell low-scale stuff from solvent. **Notice especially that the confidence might differ from the solvent definition, because OccuPy might estimate components as significant even though you said they might be solvent.** @@ -84,5 +84,5 @@ To evaluate a solvent definition, we inspect the solvent model and resulting con --- ## Final Notes -1. You can unselect a solvent definition by selecting the empty filed in the "solvent def" dropdown. A subsequent - run will not use any solvent definition. \ No newline at end of file +1. You can unselect a solvent definition by selecting the empty field in the "solvent def" dropdown. A subsequent + run will not use any solvent definition. diff --git a/docs/Tutorials/case/sub_mask.md b/docs/Tutorials/case/sub_mask.md index 407eec5..d2b77a6 100644 --- a/docs/Tutorials/case/sub_mask.md +++ b/docs/Tutorials/case/sub_mask.md @@ -20,7 +20,7 @@ A subtraction mask is to be used in e.g. RELION. Any other use should be conside

Subtraction is only remove components

-A subtraction mask can only achieve attenuation of the input data. and because it will be applied uniformly to all +A subtraction mask can only achieve attenuation of the input data. And because it will be applied uniformly to all input data, it is only appropriate for full-occupancy components. Its use is therefore currently limited to e.g. detergent regions of membrane proteins and reducing the influence of flexible regions.

@@ -31,7 +31,7 @@ detergent regions of membrane proteins and reducing the influence of flexible re ## 1. Estimate occupancy-mode local scale 1. Open the input map -2. Select occupancy-model local scale just below the modification options +2. Select occupancy-mode local scale just below the modification options 3. Estimate the scale --- @@ -50,4 +50,4 @@ detergent regions of membrane proteins and reducing the influence of flexible re 1. Without changing the modification parameters, click "Run->Generate subtraction mask" 2. The output log will report the mask(s) written, which can be opened in e.g. chimeraX. The generated mask(s) will - not be opened in the OccuPy GUI. \ No newline at end of file + not be opened in the OccuPy GUI. diff --git a/docs/Tutorials/case/supp_solv.md b/docs/Tutorials/case/supp_solv.md index ff6a363..5150b1d 100644 --- a/docs/Tutorials/case/supp_solv.md +++ b/docs/Tutorials/case/supp_solv.md @@ -8,7 +8,7 @@ Please read the GUI overview and conduct the intro tutorial first.
-To accurately suppress solvent you primarily have to make sure that the solvent model and confidence is accurate. +To accurately suppress solvent you primarily have to make sure that the solvent model and confidence are accurate. The following steps highlight factors influencing this, and how to make the necessary adjustments. --- @@ -48,7 +48,7 @@ prominent. ## Final notes -1. The confidence map is written as an auxiliary file. You Can open it manually in the chimeraX-session to have a loof +1. The confidence map is written as an auxiliary file. You can open it manually in the chimeraX-session to have a look at it if you want. You can modify and use it as a mask for other purposes as well. But beware that it will be over-written the next time you estimate the scale or modify any map, unless you change its name. 2. There is no way to diff --git a/docs/Tutorials/gui.md b/docs/Tutorials/gui.md index 235b2bc..e7c820f 100644 --- a/docs/Tutorials/gui.md +++ b/docs/Tutorials/gui.md @@ -1,9 +1,9 @@ # GUI overview -The GUI of OccuPy allows you to open maps and view them as sliced 2D images. OccuPy is not meant to visualize the +The GUI of OccuPy allows you to open maps and view them as images of 2D slices. OccuPy is not meant to visualize the map in any great detail, this is for you to make appropriate consistency checks. For fine analysis, the GUI will call out to open ChimeraX, a much more sophisticated visualization tool.

-The GUI automatically calculates and adjusts kernel settings per the users direction, and permits interactive +The GUI automatically calculates and adjusts kernel settings per the user's direction, and permits interactive evaluation of map modification.

The GUI also exposes tools to generate masks based on the estimated scale. @@ -12,7 +12,7 @@ The GUI also exposes tools to generate masks based on the estimated scale. --- ## Input map -The map to be used as input. When you run OccuPy through the GUI it will the currently selected map. +The map to be used as input. When you run OccuPy through the GUI it will indicate the currently selected map. OccuPy supports cubic .map and .mrc files. Occasionally, .ccp4 files cause issues.
@@ -40,15 +40,15 @@ There is also an "emdb" button to fetch and unzip the main map of any EMD entry. When you provide an input map, OccuPy checks the box dimensions and voxel size. Based on this, it calculates suggested parameters to estimate the local scale with accuracy and confidence. -If you change these parameters, parameters below may be updated. Changing some of these parameters will alter the +If you change these parameters, other parameters below may be updated. Changing some of these parameters will alter the local scale estimate, so leave them unchanged until you have gone through one of the specific tutorials and understand what they do.

Details depend on use

-More detailed specification of the scale kernel settings are described in the tuorials that describe estimation of -occupanvy and relative resolution, since they influence each case slightly differently. +More detailed specification of the scale kernel settings are described in the tutorials about estimation of +occupancy and relative resolution, since they influence each case slightly differently.

@@ -67,7 +67,7 @@ let you use it to modify, and inactivate the "preview" tab of the viewer and the

It's easier done than said

If you try it out and follow one or more tutorials, this will make more sense than any explanation. More detailed -specification of the modification options are e.g. described in the tutorial on map modification. +specification of the modification options are described in the tutorial on map modification.

@@ -100,8 +100,8 @@ the input anyway. ### Input The map currently selected in the "input map" drop-down menu above. ### Scale -The map currently selected in the "scale map" drop-down menu **below** the viewer. You can either add files to this -drop-down +The map currently selected in the "scale map" drop-down menu **below** the viewer. You can add files to this +drop-down either by browsing or by running OccuPy. ### Conf. The estimated solvent confidence from the previous time OccuPy was run. This is based on the estimated solvent model, @@ -112,12 +112,12 @@ The map currently selected in the "solvent def" drop-down menu below. The solven estimation of a solvent model. This is not typically required. ### Preview If you have an input and occupancy-mode scale selected, this will show a preview of the modification. **This does -not account for confidence and solvent compensation, and will look worse than the actual output**. +not account for confidence and solvent compensation, and the actual output will look better.** --- ## The output log -This will document what is happening, for our convenience. But everything is also documented in the full log, which +This will document what is happening, for your convenience. But everything is also documented in the full log, which you can access either through the menu or by double-clicking the output log *tab*.
diff --git a/docs/Tutorials/intro.md b/docs/Tutorials/intro.md index 0bf7ca0..02dedb7 100644 --- a/docs/Tutorials/intro.md +++ b/docs/Tutorials/intro.md @@ -37,7 +37,7 @@ ChimeraX from the OccuPy GUI. Please see the section for

OccuPy writes a chimeraX command script (.cxc) every time you estimate the scale or modify a map. You can open this through chimeraX instead of using OccuPy to launch chimeraX. Just make sure to use "File"->"close -session" in chimeraX before you open the .cxc-file written by OccuPy. +session" in chimeraX before you open the .cxc file written by OccuPy.

@@ -66,7 +66,7 @@ Based on the input, reasonable kernel settings were derived automatically. In th - a cube of 5 pixels (voxels) in each dimension will hold a binary mask with the above radial cutoff. - of all the pixels selected by the binary mask, the scale will be proportional to the bottom 96.47% percentile, or the top 3.53% percentile -- the above parameters results in 93 pixels (voxels) being sampled around each map pixel (voxel). +- the above parameters result in 93 pixels (voxels) being sampled around each map pixel (voxel). - a region of 12 pixels (voxels) in each dimension will be used to determine the scale-normalizing value. This value is always 12 by default, and not estimated. @@ -188,12 +188,12 @@ To understand map modification, consult the 3. Close ChimeraX ## 10. Final notes -Click "Session->View full log" in the menu field. Note that all run setting have been saved according to the same +Click "Session->View full log" in the menu field. Note that all run settings have been saved according to the same unique run-ID that you saw in the output log. This log is persistent. If you close OccuPy and start it again, the numbers will be incremented, and everything you did before and do now will be in the full log.

Maps are over-written by default. If you alter the input lowpass to 10Å and re-estimate local scale, the - previously estimated scale is gone. But the parameters to re-generate it is in the full log, provided that you + previously estimated scale is gone. But the parameters to re-generate it are in the full log, provided that you know the run ID.

You might want to play with a few more instructive maps. Here are a few entries that might be interesting to test diff --git a/docs/about.md b/docs/about.md index bd3fda9..f7cbae6 100644 --- a/docs/about.md +++ b/docs/about.md @@ -55,7 +55,7 @@ The sigmoid function originates from [Prof. Werner Antweiler](https://wernerantw The documentation format is [readthedocs](https://readthedocs.org/), using [MkDocs-material](https://squidfunk.github.io/mkdocs-material/), based on a configuration by Talley Lambert. -OccuPy is built purely in python. At it's core, it uses [numpy](https://numpy.org/), [scipy](https://scipy.org/) and +OccuPy is built purely in python. At its core, it uses [numpy](https://numpy.org/), [scipy](https://scipy.org/) and [matplotlib](https://matplotlib.org/). Additional features utilize [scikit-image](https://scikit-image.org/). diff --git a/docs/gallery/index.md b/docs/gallery/index.md index 24cb942..52ef116 100644 --- a/docs/gallery/index.md +++ b/docs/gallery/index.md @@ -2,7 +2,7 @@ Here you will find different examples of how Occupy has been used, and helped to visualise and analyze cryo-EM maps. The first section details how to use OccuPy to reproduce the images in the paper. If you have cases where it has -been useful, please consider letting one of the developer know so that we can showcase it here. +been useful, please consider letting one of the developers know so that we can showcase it here. --- diff --git a/docs/gallery/synthetic.md b/docs/gallery/synthetic.md index a0c1bd6..6cbdb13 100644 --- a/docs/gallery/synthetic.md +++ b/docs/gallery/synthetic.md @@ -14,7 +14,7 @@ OccuPy # Setup -Use a bash terminal to make a tamplate for occupancy and b-factor modification. +Use a bash terminal to make a template for occupancy and b-factor modification. ## Get and prep files ```commandline diff --git a/docs/index.md b/docs/index.md index 484a41d..417e4fc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,16 +13,16 @@ setProperty('--value', `${this.value}%`)" /> The primary purpose of OccuPy is to estimate the local scale of cryo-EM maps.

What does the 'local scale' -mean? In simple terms, think of it as the range of pixels values. In well-resolved regions, contrast is high, and we +mean? In simple terms, think of it as the range of pixel values. In well-resolved regions, contrast is high, and we expect very bright and very dark pixels. If that region has decreased resolution or occupancy, we expect decreased -contrast and a narrower range of pixel values. The limit is solvent, which has Gaussian distribution. OccuPy was built to estimate this 'scale', to quantify relative contrast degradation. This means that it can +contrast and a narrower range of pixel values. The limit is solvent, which has a Gaussian distribution. OccuPy was built to estimate this 'scale', to quantify relative contrast degradation. This means that it can estimate the relative resolution, or occupancy. OccuPy also uses this scale as a tool for map modification.


-In essence, OccuPy locates the region that exhibits the highest range of pixel values, and utilizes this to place -all other regions on a nominal scale between 0 and 1. This very useful: +In essence, OccuPy locates the region that exhibits the widest range of pixel values, and utilizes this to place +all other regions on a nominal scale between 0 and 1. This is very useful:

@@ -79,8 +79,8 @@ use that it needs no input other than a cryo-EM map. ## The gist OccuPy is currently implemented as a GUI and command-line tool using open-source python libraries, to facilitate -visualization of partial occupancy and the relative resolution of cryo-EM reconstructions by e.g implementing map +visualization of partial occupancy and the relative resolution of cryo-EM reconstructions by e.g. implementing map modification as spatial filtering based on the estimated partial occupancy of local map components. -This is intended to create maps that emulate reconstruction expected if the input (image) data was more +This is intended to create maps that emulate the reconstruction expected if the input (image) data was more homogenous at lower or higher occupancy. diff --git a/docs/install.md b/docs/install.md index 700736f..3e2a641 100644 --- a/docs/install.md +++ b/docs/install.md @@ -14,7 +14,7 @@ Compiled binaries will not be updated as new bugfixes get implemented. Once alph will be provided.

Using pip install, you can get bugfixes at any time, and update according to the latest changes. If you don't want -to wait for a new release of bug-fixes, install with pip from source, as described below). +to wait for a new release of bug-fixes, install with pip from source (as described below).

@@ -71,7 +71,7 @@ Occupy GUI version :fontawesome-solid-tag: 0.1.9 (alpha). === "Windows" 1. Download the binary installer. - 2. Double-click the installer, which should guide you thorugh the simple process of installing OccuPy on your + 2. Double-click the installer, which should guide you through the simple process of installing OccuPy on your system. 3. In the start-menu, search for "occupy_gui". You should see the OccuPy Guppy. @@ -81,7 +81,7 @@ Occupy GUI version :fontawesome-solid-tag: 0.1.9 (alpha). 2. Open a terminal and navigate to the downloads directory. 3. In the terminal, type `chmod a+x occupy_gui`. 4. In a file browser, go to the downloads directory and right-click the `occupy_gui` binary and select 'Open'. - In the dialog that pops up, select 'Open again'. You can also type `./occupy_gui` in the terminal + In the dialog that pops up, select 'Open' again. You can also type `./occupy_gui` in the terminal === "Linux (ubuntu)" @@ -95,7 +95,7 @@ Occupy GUI version :fontawesome-solid-tag: 0.1.9 (alpha). If you have issues using the pre-compiled binaries, please check the troubleshooting section.

-Previous versions of OccuPy are **not** available as binaries, but only though [PIP](https://pypi. +Previous versions of OccuPy are **not** available as binaries, but only through [PIP](https://pypi. org/project/OccuPy/) and [github](https://github.com/bforsbe/OccuPy). The same goes for the command-line tool. Installation through PIP is described below. @@ -121,12 +121,12 @@ If you run into issues, check the tro The following contains elements of [this](https://www.digitalocean.com/community/tutorials/install-python-windows-10) guide to installing python on windows, and - [this](https://pip.pypa.io/en/stable/installation/#get-pip-py) guide to install pip using python. + [this](https://pip.pypa.io/en/stable/installation/#get-pip-py) guide to installing pip using python. 1. In the start-menu, type "Powershell". Open a powershell, which is a text-based interface to run system commands. 2. Check if python is installed by running the command `python --version` in the powershell. If you see a version number, python is installed. - If not, download and click the python3.10 installer for windows, which you can get thorugh + If not, download and click the python3.10 installer for windows, which you can get through [this link](https://www.python.org/ftp/python/3.10.8/python-3.10.8-amd64.exe). Follow the instructions on screen to install. 3. Close the powershell and reopen it once python is installed. @@ -171,8 +171,8 @@ If you run into issues, check the tro === "Linux (ubuntu)" - It is recommended that you install occupy using a clean conda or other virtual environment, as this will avoid potential - conflict with pre-existing packages and specifically their conflicint dependencies on pyqt. + It is recommended that you install occupy using a clean conda or other virtual environment, as this will prevent potential + conflict with pre-existing packages and specifically their conflicting dependencies on pyqt. 1. Open a terminal. 2. In the terminal, call `pip install occupy[pyqt5]`. @@ -189,7 +189,7 @@ If you run into issues, check the tro 1. Open a terminal. 2. In the terminal, call `pip install occupy` if your mac has an M1 chip. Otherwise you will likely need to instead - need to call `pip install occupy[pyqt5]` + call `pip install occupy[pyqt5]` 3. Verify the install by calling `pip show occupy`. You will either see `WARNING: Package(s) not found: occupy` or a description of the installation. If successfully installed, continue. 4. In the terminal, call `occupy_gui`. If you get the error @@ -254,7 +254,7 @@ We recommend you do this in a virtual environment. More on this and specific dev ## Usage ### The GUI Occupy has a GUI that is recommended to use, because it makes the processing steps more intuitive, presents the -options plainly, and offer easy ways to check your input and processing results for consistency. +options plainly, and offers easy ways to check your input and processing results for consistency. To **start the GUI** from the command-line (terminal) and it is in your path (e.g. if you used pip install), simply call @@ -306,13 +306,13 @@ pyinstaller --onefile --windowed occupy_lib/occupy_gui.py ls dist ``` -5. build docs and start a local serve to view them (interactive with changes) +5. build docs and start a local server to view them (interactive with changes) ```shell mkdocs serve ``` ### The python module -For development use, you can also import it as a python module, but this currently and unsupported feature that we +For development use, you can also import it as a python module, but this is currently an unsupported feature that we will not prioritize as main functionality. ```python