SEE Cation-Pi-ToDo.docx !!!

To follow Cation-Pi when upgrading to angle/distance or Ajax, enable in scripts.js alerts
29, 33, 108a, 106a, 33b.

FG 4.7
 - Justin Gallivan upgraded CaPTURE.
		+ It handles insertion codes, lower case chain IDs and multiple-character chain IDs.
    + It handles CIF files.
    + It supports Ajax with tab-delimited results.
				https://bioinformatics.org/molvis/ajax2capture.htm
    - Does not yet default to BU1.
    - Messes up altlocs. 3Lkt.
    - No mechanism yet to upload AlphaFold etc.

I had largely implemented angle/distance calculations and listing,
but not yet done analysis to see how much
improvement this could make in detection.
But now FG could use Ajax to get CaPTURE results ...
	but not yet for BUs.

Decided to postpone releasing the angle/distance stuff to get 4.7 released (ConSurf Temperature,
new Animation generator).

Query parameter newcatpi switches to use the new unfinished angle/distance and listing code.
Without it, the old 3-carbon method and listing with lots of warnings.

meg "newcatpi" will find all key points in the code.

----------------------
For FG4.3, I discovered that, contrary to other classes of targ/cont terms,
	// ~targ_catpi is both target cations and outside rings,
	// ~cont_catpi is both outside cations and target rings.
Therefore I defined ~catpi_in_target and ~catpi_contacting_target.

4.3:
	Fixed a bug that clicking the contacts catpi checkbox failed to make correct ~cont_catpi
		in makeContactsViewSpt() (scripts.js).
---------------------
For comparisions of the results of the new vs. old routines, see residue-by-residue analyses
in catpi.docx.

catPiSBNow and preContactsNow are external variables (from doViewLink).

---------------------
The old code found cations and rings where the 3 key ring atoms were within 6
of ANY cations. The cations could be multiple residues, so that no single
cation residue was within 6 of all 3 key ring atoms. Result was display
of a ring with no cation.

This case showed a ring with no nearby cation.
Example: Tyr6 in 4enl.
The 3 key ring atoms in Tyr6 are within 6 of Lys4 or Arg8, but no atoms in those
cationic residues are within 6 of all 3 key ring atoms.

This case showed Arg141:A and :C unpaired with rings.

The new code finds cation candidates and then verifies each one by looping
through the nearby rings one ring at a time to see if any single ring has all 3
key atoms within 6. Unpaired residues disappeared with new code.

The trick was to learn how to loop per residue. Could be done either with *.ca
or groupindex (unique index number per residue). I chose groupindex in case of
the unlikely possibility that a residue with cation atoms might be missing
its alpha carbon. See test scripts in molvis/jmol_tests/loop-per-residue/

BUT the new code gets very slow for large structures. Thus I decided to use the old code
when >10,000 atoms, and the new code only when fewer (about 90% of entries).

                           Seconds*                      Report
             Protein  –––––––––––––––––––        ––––––––––––––––––––––––
PDBId Atoms   kDa     Old Code   New Code        Cations  Rings  NTermini
–––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
6mt3    4K      42                                 10      10     1
2v61    9K     104                5.4              17      16     0
2cvo   12K     142                6.5,6.5          11      15     0
5ibx   17K     196    5.3,4.8§   15.7,12.8,13      24      32     0
                      7.5¶
7ahl   23K     220    4.9        20.4              36      33     7
                      11.2,10.6¶
6n0x   31K     216               22
–––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
* With 'Report Elapsed Times' on, from "doViewLink(makeCatPiSBSpt()) starting (jcontrol.js)"
to "BUSY-OFF from scriptToJmol() (consurf/msgcall.js)".
§ Replicate measurements.
¶ With per-residue code for ends only.
FOR OTHER PDB ENTRY SIZES SEE PROTEOPEDIA JSMOL NOTES.

-------------------------------------------------------------------------
METHOD
-------------------------------------------------------------------------
The Tools tab SB/CatPi EXECUTES (via doViewLink(N) in jcontrol.js) the RETURN from
	makeCatPiSBSpt() (scripts.js) and makeCatPiSBHelp() (help.js).

// Compare Tools -> Contacts & Non-Covalent Bonds -> (after selection) showContacts()
	which executes makeGenerateContactsSpt() -> makeDefineContactsSpt() 
	and makeRenderCatPiSBSpt() //

makeCatPiSBSpt() RETURNS makeCatPiSBSpt2() (scripts.js)
	selectedFound = ((LYS, DLY, ARG, DAR) and not backbone) + N-termini

	makeDefineContactsSpt() (used for both SB & CatPi)
		[ + makeRenderCatPiSBSpt();]

		makeSelectSpt() ~contarget = ~targ_current = selectedFound and not hydrogen nor hidden.
			~outside_contarget is everything else except hydrogen.
			>>> So ~contarget is cations, ~outside_contarget includes rings.
				makeCatPiContactsSpt() formerly -> makeCatPiContOldSpt() (fast, inaccurate)
					4.7: makeCatPiContNewSpt() (uses ring centers vs. cationPiCutoff)

				makeCatPiTargetsSpt()
				makeCatPiEndsSpt(); [also called by makeCatPiContOldSpt(), inacc mtd] 

The controls in the CatPiSB help panel call renderCatPiSB() (scripts.js) which calls
makeRenderCatPiSBSpt() 

- - - - - -
LIST added FG 4.7 (still inaccurate! just for ease of comparison with CaPTURE)

NOT IN USE: JMOL FUNCTION listCatPI() (util.js)
	In catpilist, it generates an atom pair list in residue order within chain. NOT WANTED.

listCationPi(), listCationPi2() (help1.js) generate the list,
	calling getCationPiList() (help1.js) to make the body of the table.


- - - - - -
FAST FLAWED VS SLOW BETTER DETECTION:

The original code for catpi detection was flawed (but fast). It detects some pairs
that are invalid and also detects some unpaired cations or rings: see example
in catpi.docx.

For FGiJ 3.0, new code fixes that bug by looping per residue. But the new code is slow.
So new code is used only when the total non-H atoms <= 12K
allAtomNonHM1C1Count <= catPiLimitNewAlgorithm

For larger models, the old buggy fast code is still used, but the help displays an option
to re-detect catpi with more accurate code, which uses
	reDetectCatPi() which sets
		detectCatPiPerResidueOnce = true; ****
			and then calls madeCatPiSBSpt2() NOTE THE 2, which calls
				makeDefineContactsSpt()
					makeCatPiContactsSpt(), makeCatPiTargetsSpt() <<<<
						makeCatPiContPerResidueSpt(); (when ...Once is true ****)
							makeCatPiEndsSpt(); [also called by makeCatPiContOldSpt(), inacc mtd] 

RING CENTER ATOMS (HOLMIUM)
It is >>>> makeCatPiTargetsSpt() that generates ~createRCASpt


-------------------------------------------------------------------------
OLD CODE USED PRIOR TO FGIJ 3.0 (NOW USED ONLY FOR LARGE MODELS).
-------------------------------------------------------------------------

	// CATION PI CONTACTS 
	// cation sidechains outside target
"select (~outside_contarget and (lys.ce,lys.nz,arg.cz,arg.cd) " +
"and within(6.0, (~contarget and (trp.cd2,tyr.cd1,phe.cd1))) " +
"and within(6.0, (~contarget and (trp.cz2,tyr.cd2,phe.cd2))) " +
"and within(6.0, (~contarget and (trp.cz3,tyr.cz,phe.cz))));\n" +
"define ~ocatpi0 selected;\n" +
	// ~ocatpi0 = catpi nitrogen cations.

	// pi rings
"select (~outside_contarget and (trp.cd2,tyr.cd1,phe.cd1) " +
"and within(6.0, (~contarget and (lys.ce,lys.nz,arg.cz,arg.cd)))); \
select within(group, selected);\n\
define ~ocatpi1 selected;\n" +

"select ~ocatpi1 and (trp.cz2,tyr.cd2,phe.cd2) " +
"and within(6.0, (~contarget and (lys.ce,lys.nz,arg.cz,arg.cd)));\n\
select within(group, selected);\n\
define ~ocatpi2 selected;\n" +

"select ~ocatpi2 and (trp.cz3,tyr.cz,phe.cz) " +
"and within(6.0, (~contarget and (lys.ce,lys.nz,arg.cz,arg.cd)));\n" +
"select within(group, selected);\n" +
"define ~ocatpi3 selected;\n" +


	// catpi aromatic residues are now selected.
	// Next, restrict selection to 6-carbon rings.

"select selected and (trp.cd2,trp.ce?,trp.cz?,trp.ch?, " +
"phe.cg,phe.cd?,phe.ce?,phe.cz, " +
"tyr.cg,tyr.cd?,tyr.ce?,tyr.cz);\n\
select selected or ~ocatpi0;\n\
define ~cont_catpi_noends selected;\n" +

-------------------------------------------------------------------------

	// CATION PI TARGETS
	// cation sidechains in target
"select (~contarget and (lys.ce,lys.nz,arg.cz,arg.cd) " +
"and within(6.0, (~outside_contarget and (trp.cd2,tyr.cd1,phe.cd1))) " +
"and within(6.0, (~outside_contarget and (trp.cz2,tyr.cd2,phe.cd2))) " +
"and within(6.0, (~outside_contarget and (trp.cz3,tyr.cz,phe.cz))));\n" +
"define ~tcatpi0 selected;\n" +

	// pi rings
"select (~contarget and (trp.cd2,tyr.cd1,phe.cd1) " +
"and within(6.0, (~outside_contarget and (lys.ce,lys.nz,arg.cz,arg.cd)))); \
select within(group, selected);\n\
define ~tcatpi1 selected;\n" +

"select ~tcatpi1 and (trp.cz2,tyr.cd2,phe.cd2) " +
"and within(6.0, (~outside_contarget and (lys.ce,lys.nz,arg.cz,arg.cd)));\n\
select within(group, selected);\n\
define ~tcatpi2 selected;\n" +

"select ~tcatpi2 and (trp.cz3,tyr.cz,phe.cz) " +
"and within(6.0, (~outside_contarget and (lys.ce,lys.nz,arg.cz,arg.cd)));\n\
select within(group, selected);\n" +
"define ~tcatpi3 selected;\n" +


	// target ring residues selected
	// next narrow to 6 carbon rings

"select selected and (trp.cd2,trp.ce?,trp.cz?,trp.ch?, " +
"phe.cg,phe.cd?,phe.ce?,phe.cz, " +
"tyr.cg,tyr.cd?,tyr.ce?,tyr.cz);\n\
select selected or ~tcatpi0;\n\
define ~targ_catpi_noends selected;\n" +

	// GATHER CATPI GROUPS
"select ~cont_catpi_noends, ~cont_catpi_nterm, ~cont_catpi_endrings;\n" +
"define ~cont_catpi selected;\n" +
"define ~catpi_rings selected;\n" +
"select ~targ_catpi_noends, ~targ_catpi_nterm, ~targ_catpi_endrings;\n" +
"define ~targ_catpi selected;\n" +
"define ~catpi_cations selected;\n" +

"select within(group, (~catpi_cations, ~catpi_rings));\n" +
"define ~catpi_amino_acids selected;\n";

-------------------------------------------------------------------------
ENDS

// End-N to rings
"select ~chargedEndNitrogens " +
"and within(6.0, (trp.cd2,tyr.cd1,phe.cd1)) " +
"and within(6.0, (trp.cz2,tyr.cd2,phe.cd2)) " +
"and within(6.0, (trp.cz3,tyr.cz,phe.cz));\n" +
"define ~cont_catpi_nterm (selected and ~outside_contarget);\n" +
"define ~targ_catpi_nterm (selected and ~contarget);\n" +
"define ~catpi_nterm selected;\n" +

// Rings to end-N
"select (trp.cd2,tyr.cd1,phe.cd1) and within (6.0, ~catpi_nterm);\n" +
"select within(group, selected);\n" +
"select selected and (trp.cz2,tyr.cd2,phe.cd2) and within (6.0, ~catpi_nterm);\n" +
"select within(group, selected);\n" +
"select selected and (trp.cz3,tyr.cz,phe.cz) and within (6.0, ~catpi_nterm);\n" +
"select within(group, selected);\n" +

	// Ring to End-N CatPi residues are now selected. Next restrict to ring 6-carbons.
"select selected and (trp.cd2,trp.ce?,trp.cz?,trp.ch?, " +
"phe.cg,phe.cd?,phe.ce?,phe.cz, " +
"tyr.cg,tyr.cd?,tyr.ce?,tyr.cz);\n" +

	//Define targ and cont rings
"define ~catpi_endrings selected;\n" +
"define ~cont_catpi_endrings (~catpi_endrings and ~outside_contarget);\n" +
"define ~targ_catpi_endrings (~catpi_endrings and ~contarget);\n";


-------------------------------------------------------------------------
-------------------------------------------------------------------------