Merge branch 'develop' of github.com:RBVI/ChimeraX into feature/profi…

…le-grids

.gitignore

@@ -30,6 +30,7 @@ Thumbs.db
 # Test files
 .coverage
 *htmlcov
+debugging_scripts
 #
 errs*
 build

.readthedocs.yaml

@@ -11,6 +11,7 @@ build:
     post_checkout:
       - git fetch --unshallow
     post_install:
+      - curl https://cxtoolshed.rbvi.ucsf.edu/prereqs/grako/grako-3.16.5-py2.py3-none-any.whl --output grako.whl && python -I -m pip install ./grako.whl
       - python -I -m pip install setuptools==65.1.1
       - python -I -m pip install -r prereqs/pips/build_requirements.txt
       - python -I -m pip install prereqs/qtshim

Makefile

@@ -170,7 +170,7 @@ ifeq (,$(SNAPSHOT_DIR))
 endif
 	mkdir $(SNAPSHOT_DIR)
 	echo "branch: $(SNAPSHOT_TAG)" > $(SNAPSHOT_DIR)/last-commit
-	git show --summary --date=iso $(SNAPSHOT_TAG) >> $(SNAPSHOT_DIR)/last-commit
+	git show --summary --date=iso --pretty=fuller $(SNAPSHOT_TAG) >> $(SNAPSHOT_DIR)/last-commit
 	git archive $(SNAPSHOT_TAG) | tar -C $(SNAPSHOT_DIR) -xf -
 
 include $(TOP)/Makefile.tests

Makefile.flatpak

@@ -1,5 +1,7 @@
 APPNAME = edu.ucsf.rbvi.ChimeraX
 BUILD_DIR = fp-build.tmp
+RUNTIME_VER = 23.08
+BRANCH = $(shell awk '$$1 == "branch:" { print $$2; exit } { exit 3 }' last-commit 2> /dev/null || git branch --show-current)
 
 all:
 	# by default, do nothing
@@ -10,25 +12,32 @@ preqreqs-rhel:
 prereqs-ubuntu:
 	apt install flatpak flatpak-builder gnome-software-plugin-flatpak
 
-build-flatpak:
+prereqs-flatpak:
+	flatpak install -y org.freedesktop.Sdk//${RUNTIME_VER}
+
+
+build-flatpak: ${APPNAME}.yaml
 	flatpak-builder --force-clean ${BUILD_DIR} ${APPNAME}.yaml
 
+${APPNAME}.yaml: ${APPNAME}.yaml.in
+	sed -e 's:RUNTIME_VER:${RUNTIME_VER}:' -e 's:BRANCH:${BRANCH}:' $< > $@ || rm $@
+
 clean:
-	rm -f ${APPNAME}.metainfo.xml ${APPNAME}.desktop
-	rm -rf ${BUILD_DIR}
+	rm -f ${APPNAME}.metainfo.xml ${APPNAME}.desktop ${APPNAME}.yaml
+	rm -rf ${BUILD_DIR} .flatpak-builder
 
 install:
 	# this is called indirectly by flatpak-builder via yaml/json manifest
 	mkdir -p /app
-	$(MAKE) install NO_PREBUILT=1 FLATPAK_DIST=22.08 FLATPAK_APPNAME=${APPNAME}
+	$(MAKE) install NO_PREBUILT=1 FLATPAK_DIST=${RUNTIME_VER} FLATPAK_APPNAME=${APPNAME}
 	install -Dm644 -t /app/share/metainfo ${APPNAME}.metainfo.xml
 	install -Dm644 -t /app/share/applications ${APPNAME}.desktop
 
-user-install:
+user-install: ${APPNAME}.yaml
 	# assume it has been built already
 	flatpak-builder --export-only --user --install ${BUILD_DIR} ${APPNAME}.yaml
 
-system-install:
+system-install: ${APPNAME}.yaml
 	# assume it has been built already
 	flatpak-builder --export-only --system --install ${BUILD_DIR} ${APPNAME}.yaml
 
@@ -43,7 +52,10 @@ run:
 explore:
 	flatpak run --command=sh ${APPNAME}
 
-explore-sdk:
+explore-dev:
+	flatpak run -d --command=sh ${APPNAME}
+
+explore-sdk: ${APPNAME}.yaml
 	flatpak run $(shell grep ^sdk ${APPNAME}.yaml | cut -d ' ' -s -f 2)
 
 validate-metainfo:

docs/contact.html

@@ -46,8 +46,10 @@ <h2>UCSF ChimeraX: Contact Us</h2>
 You can
 <a href="https://mail.cgl.ucsf.edu/mailman/mailman3/lists/chimerax-users.cgl.ucsf.edu/">
 subscribe</a> to the list,
-<a href="https://mail.cgl.ucsf.edu/mailman/archives/list/[email protected]/">
-view</a> the archive, or search the archive:
+or <a href="https://mail.cgl.ucsf.edu/mailman/archives/list/[email protected]/">
+view/search</a> the archive.
+<!--
+, or search the archive:
 <p>
 <form style="margin-bottom: 0px;" action="https://www.google.com/search" name="f">
 <input type="hidden" name="hl" value="en">
@@ -59,6 +61,7 @@ <h2>UCSF ChimeraX: Contact Us</h2>
 <input type="submit" name="btnSearch" value="Google&#153 chimerax-users archive">
 </td></tr></table>
 </form>
+-->
 
 <dt><h4><a name="bugs">To report a problem with ChimeraX:</a></h4>
 <dd>

docs/credits.html

@@ -51,6 +51,11 @@ <h2>Citing UCSF ChimeraX</h2>
 <li>cite one or more of the 
 <a href="morerefs.html">ChimeraX references</a>, mainly:
 <blockquote>
+<a href="https://onlinelibrary.wiley.com/doi/10.1002/pro.4792" target="_blank">
+UCSF ChimeraX: Tools for structure building and analysis.</a>
+Meng EC, Goddard TD, Pettersen EF, Couch GS, Pearson ZJ, Morris JH, Ferrin TE.
+Protein Sci. 2023 Nov;32(11):e4792.
+<br><br>
 <a href="https://www.ncbi.nlm.nih.gov/pubmed/32881101" target="_blank">
 UCSF ChimeraX: Structure visualization for researchers, educators,
 and developers.</a>
@@ -80,12 +85,13 @@ <h3>Authors</h3>
 <ul type=none>
 <li><a href="https://www.rbvi.ucsf.edu/home/tef/">Thomas Ferrin</a> 
 &ndash; principal investigator
-<li>Conrad Huang &ndash; project leader
-<li>Eric Pettersen &ndash; atomic structure analysis, sequence-structure linkage
-<li>Tom Goddard &ndash; density maps, hierarchical models, rendering
+<li>Eric Pettersen &ndash; atomic structure analysis, sequence-structure tools
+<li>Tom Goddard &ndash; density maps, rendering, virtual and augmented reality
+<li>Zach Pearson &ndash; web services, medical image tools
 <li>Greg Couch &ndash; infrastructure, I/O
 <li>Elaine Meng &ndash; user documentation, web content
 <li>Scooter Morris &ndash; project management
+<li>Conrad Huang &ndash; former project leader (retired)
 </ul>
 ... and numerous collaborators, to whom we are grateful for 
 thoughtful suggestions and time spent evaluating features. 

docs/devel/building.rst

@@ -98,6 +98,9 @@ Steps for compiling ChimeraX on Windows 10:
 #. Clone the `ChimeraX repository <https://github.com/RBVI/ChimeraX>`_ from GitHub.
 
 #. Run ". ./vsvars.sh" in chimerax root directory to set path to Visual Studio compiler.
+   If you use different Microsoft SDK or build tools versions then you will need to edit
+   the vsvars.sh script to use your versions.  If you do not it will not give any errors
+   but all compilations will mysteriously fail.
 
 #. "make install" in the repository root.
 

docs/devel/class_munger.py

@@ -26,7 +26,11 @@
     (r"\.ui\.cmd\b", ".ui"),
     (r"\.ui\.font\b", ".ui"),
     (r"\.ui\.mousemodes\b", ".ui"),
-    (r"\.ui\.widgets.htmlview\b", ".ui.widgets"),
+    (r"\.ui\.widgets\.htmlview\b", ".ui.widgets"),
+    (r"\.ui\.widgets\.item_chooser\b", ".ui.widgets"),
+    (r"\.ui\.widgets\.item_table\b", ".ui.widgets"),
+    (r"\.ui\.options\.options\b", ".ui.options"),
+    (r"\.ui\.options\.containers\b", ".ui.options"),
 
     # hide chimerax.atomic submodules
     (r"\.atomic\.molobject\b", ".atomic"),

docs/devel/conf.py.in

@@ -288,9 +288,10 @@ intersphinx_mapping = {
     'matplotlib': ('https://matplotlib.org/stable/', None),
     'numpy': ('https://numpy.org/doc/stable/', None),
     'python': ('https://docs.python.org/PYTHON_VERSION', None),
-    'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/', None),
     'sphinx': ('https://www.sphinx-doc.org/en/master', None),
-    'setuptools': ('https://setuptools.readthedocs.io/en/latest/', None),
+    'setuptools': ('https://setuptools.pypa.io/en/latest/', None),
+    'pillow': ('https://pillow.readthedocs.io/en/latest/', None),
 }
 
 # -- Options for extlinks --------------------------------------------

docs/devel/conventions.rst

@@ -32,6 +32,7 @@ them up automatically.
 Editor Defaults
 ---------------
 .. From <http://wiki.python.org/moin/Vim>:
+
 All python files should have the following modeline at the top: ::
 
     # vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4:

docs/devel/tutorials/bundle_info.rst

@@ -834,14 +834,19 @@ The other possible `Provider`_ attributes are:
 
     *pregrouped_structures*
         If a provider returns multiple models, the open command will automatically group them
-        so that the entire set of models can be referenced with one model number (the individual
-        models can be referenced with submodel numbers).  The provider *could* pre-group them in
-        order to give the group a name other the default (which is based on the file name; the user can
-        still override that with the ``name`` keyword of the open command).  In the specific case
-        where the provider is pre-grouping atomic structures, it should specify *pregrouped_structures*
-        as "true" so the the open command's return value can be the actual list of structures rather
-        than a grouping model.  This greatly simplifies scripts trying to handle return values
-        from various kinds of structure-opening commands.
+        (see ``group_multiple_models`` attribute, next) so that the entire set of models can be referenced
+        with one model number (the individual models can be referenced with submodel numbers).
+        The provider *could* pre-group them in order to give the group a name other the default
+        (which is based on the file name; the user can still override that with the ``name`` keyword
+        of the open command).  In the specific case where the provider is pre-grouping atomic structures,
+        it should specify *pregrouped_structures* as "true" so the the open command's return value can be
+        the actual list of structures rather than a grouping model.  This greatly simplifies scripts trying
+        to handle return values from various kinds of structure-opening commands.
+
+    *group_multiple_models*
+        By default, if a provider returns multiple models they will be grouped for ease of reference
+        in commands.  If it is desired that the returned models each be separate top-level models,
+        specify a value of "false" for this attribute.
 
     *type*
         If you are providing information about opening a file rather than fetching from a
@@ -1005,15 +1010,17 @@ The other possible `Provider`_ attributes are:
 
 - **Frequently-Used** Attributes
 
-    *example_ids*
-        A list of one or more valid example identifiers for your database.  For use in
-        graphical user interfaces.
-
     *synopsis*
         The description of the fetcher used by user-interface widgets that list fetchers
-        (like the Fetch By ID dialog in Chimera), so typically somewhat more verbose than *name*.
-        The first word should be capitalized unless that word is mixed case (*e.g.* mmCIF).
-        Defaults to a capitalized *name* followed by the *format_name* in parentheses.
+        (such as the Fetch By ID dialog), so typically somewhat more verbose than *name*.
+        Words should be capitalized unless that word is mixed case (*e.g.* mmCIF).
+        Omitting *synopsis* means that the fetcher will not be listed in user-interface widgets.
+        The ';' character can be used to separate lines of a multi-line description.
+
+    *example_ids*
+        A list of one or more valid example identifiers for your database.  For use in
+        graphical user interfaces (see *synopsis* attribute).
+        The ';' character can be used to separate multiple example IDs.
 
 - **Infrequently-Used** Attributes
 
@@ -1025,14 +1032,19 @@ The other possible `Provider`_ attributes are:
 
     *pregrouped_structures*
         If a provider returns multiple models, the open command will automatically group them
-        so that the entire set of models can be referenced with one model number (the individual
-        models can be referenced with submodel numbers).  The provider *could* pre-group them in
-        order to give the group a name other the default (which is based on the database entry ID;
-        the user can still override that with the ``name`` keyword of the open command).
-        In the specific case where the provider is pre-grouping atomic structures, it should specify
-        *pregrouped_structures* as "true" so the the open command's return value can be the actual list
-        of structures rather than a grouping model.  This greatly simplifies scripts trying to handle
-        return values from various kinds of structure-opening commands.
+        (see ``group_multiple_models`` attribute, next) so that the entire set of models can be referenced
+        with one model number (the individual models can be referenced with submodel numbers).
+        The provider *could* pre-group them in order to give the group a name other the default
+        (which is based on the database entry ID; the user can still override that with the ``name``
+        keyword of the open command).  In the specific case where the provider is pre-grouping atomic
+        structures, it should specify *pregrouped_structures* as "true" so the the open command's
+        return value can be the actual list of structures rather than a grouping model.  This greatly
+        simplifies scripts trying to handle return values from various kinds of structure-opening commands.
+
+    *group_multiple_models*
+        By default, if a provider returns multiple models they will be grouped for ease of reference
+        in commands.  If it is desired that the returned models each be separate top-level models,
+        specify a value of "false" for this attribute.
 
 For example::
 

docs/devel/tutorials/pyproject.rst

@@ -88,7 +88,7 @@ the source tree, respectively. ::
 The general syntax is ``"target/directory" = ["list", "of", "source", "files"]``.
 
 Platform-Specific Extra Files
-----------------------------
+-----------------------------
 You may choose to optionally include some extra files on certain platforms only. In this
 case put them in a table such as: ::
 
@@ -341,7 +341,7 @@ initializer are available in Bundle Builder with two additions:
 
   and
 
-- ``lib-modules``
+- ``library-modules``
 
 Each is expected to be a list of python modules on which your extension, library, 
 or executable depends. At build time, Bundle Builder will attempt to import the 
@@ -375,7 +375,7 @@ exposed in bundle builder:::
     language = ""
     optional = false
     include-modules = []
-    lib-modules = []
+    library-modules = []
 
 Notes:
 

docs/devel/tutorials/tutorial_hello.rst

@@ -87,7 +87,7 @@ attributes are:
 - ``package``: the name of the Python package where ChimeraX
   can find the code for this bundle, and
 - ``minSessionVersion`` and ``maxSessionVersion``: the minimum
-  and maximum sessionf file versions that the bundle supports.
+  and maximum session file versions that the bundle supports.
 
 The next few tags supply information about who wrote the bundle,
 where to find more information on the web, as well as short

docs/devel/tutorials/tutorial_tool_qt.rst

@@ -326,6 +326,34 @@ Some tools may use multiple windows (created via the :py:class:`~chimerax.ui.Mai
 the tool window will start out tabbed with the other window.
 
 
+A Useful Aside
+++++++++++++++
+
+In addition to the wealth of generic UI widgets provided by the Qt library, ChimeraX provides some
+special-purpose widgets useful for leveraging ChimeraX's capabilities easily.  They are:
+
+Data lists/menus
+    Used for choosing one or more models, structures, chains, etc.  Basic classes (:py:class:`~chimerax.ui.widgets.item_chooser.ModelListWidget`
+    *et al*.) described in :py:mod:`chimerax.ui.widgets.item_chooser`, and atomic-model specific classes in :py:mod:`chimerax.atomic.widgets`.  Can be extended to volumes
+    and other data types by using the :py:attr:`class_filter` contructor keyword.
+
+Remember-able options
+    The :ref:`chimera.ui.options <option_widgets>` module provides interface widgets for specifiying numbers,
+    strings, file names, passwords, colors, and more.  These options can interoperate with a
+    :py:class:`~chimerax.core.settings.Settings` object to remember those settings, and will react to changes to that Settings object
+    to always display the up-to-date value.  These options are designed to placed in "container"
+    classes (*e.g.* :py:class:`~chimerax.ui.options.containers.SettingsPanel`, also in the :py:mod:`~chimerax.ui.options` module) that
+    lay out the options into columns that align their labels and their value widgets.
+
+Python-data tables
+    The :ref:`chimera.ui.widgets <python_data_tables>` module provides an :py:class:`~chimerax.ui.widgets.item_table.ItemTable` class for showing Python objects as rows of a table and columns that show values derived from those objects (frequently attributes) as columns.
+    The table columns are sortable and table cells are optionally editable.
+    Balloon help can be shown for column headers and columns can be hidden/shown as needed.
+    A signal is emitted when the selection in the table changes so that other widgets in your
+    interface can be updated.  Querying the table for its current selection (:py:attr:`selected` attribute) will return the
+    Python objects corresponding to the selected rows rather than row numbers.
+
+
 .. _context-menu:
 
 Context Menu

docs/index.html

@@ -40,7 +40,7 @@ <h2>UCSF ChimeraX Documentation Index</h2>
 <li><a href="https://www.rbvi.ucsf.edu/chimerax/tutorials.html">Tutorials</a>
 <li><a href="videos/index.html">How-To Videos</a>
 <li><a href="presentations.html">Demonstrations</a>
-<li><a href="https://www.rbvi.ucsf.edu/pipermail/chimerax-users/index.html">Mailing list</a>
+<li><a href="https://mail.cgl.ucsf.edu/mailman/mailman3/lists/chimerax-users.cgl.ucsf.edu/">Mailing list</a>
 <li><a href="contact.html">Contact Us</a>
 </ul>
 <br>

docs/morerefs.html

@@ -29,6 +29,11 @@ <h2>UCSF ChimeraX References</h2>
 Primary references:
 </p>
 <blockquote>
+<a href="https://onlinelibrary.wiley.com/doi/10.1002/pro.4792" target="_blank">
+UCSF ChimeraX: Tools for structure building and analysis.</a>
+Meng EC, Goddard TD, Pettersen EF, Couch GS, Pearson ZJ, Morris JH, Ferrin TE.
+Protein Sci. 2023 Nov;32(11):e4792.
+<br><br>
 <a href="https://www.ncbi.nlm.nih.gov/pubmed/32881101" target="_blank">
 UCSF ChimeraX: Structure visualization for researchers, educators,
 and developers.</a>

docs/presentations.html

@@ -38,6 +38,10 @@ <h2>ChimeraX Demonstrations, Talks and Posters</h2>
 <a href="https://rbvi.github.io/chimerax-recipes/">ChimeraX recipes</a>
 </p>
 
+<p>
+<a href="https://www.rbvi.ucsf.edu/chimerax/data/alphapairs-oct-2023/alphapairs.html">Find protein-protein interactions with AlphaFold</a>. October 10, 2023.
+</p>
+
 <p>
 <a href="https://www.rbvi.ucsf.edu/chimerax/data/gltf-viewer-may2023">How to embed a ChimeraX scene in a web page</a>. May 23, 2023.
 </p>