Package: cowboe
COWBOEConstruction Of Windows Based on free EnergyWhat is cowboeCOWBOE is a python 3 tool for parameter selection in Umbrella Sampling which is a free energy calculation method used in Molecular dynamics simulations.FeaturesIt is a Python 3 module hence easy to install.Parameter selection which tunes the total number of windows and force constants used with Umbrella sampling are done.Parameters are optimized using Nelder-mead / Restricted Nelder-Mead simplex optimization algorithm.Progress of the optimization can be tracked.Module includes functions to perform comparison and visualization of different PMFs (Potential of Mean Forces / Free energy files) and the NM algorithm results.Installationcowboe requires Python V3.7 or higher  to run.Creating a virtual environmentIt is best to install cowboe in a new environmentUsing venvFor Linux/macOS,python3-mvenv/path/to/new/virtual/environmentsource<venv>/bin/activateFor Windows,c:\>python-mvenvc:\path\to\myenv
c:\><venv>\Scripts\activate.batUsing condacondacreate-ncowboepython=3.9
condaactivatecowboeInstalling pippip is already installed if you are using Python 3 >=3.4 downloaded from python.org or if you are working in a Virtual Environment created by virtualenv or venv. Just make sure to upgrade pip using,python3-mpipinstall--upgradepipInstalling cowboecowboe is available on pypi and can be installed using pip as follows,pipinstallcowboeBuilding from sourceDownload the source as a zip file from GitHub and extract the files to a new folder. Before building cowboe install the dependencies using pip as shown below and it will resolve all dependencies conflicts.cd<locationofextractedfileswithsetup.pyfile>
pip3installnumpyscipymatplotlibseabornshapelyimageiopandas
pythonsetup.pyinstallAfter the installation cowboe module should be available and it can be checked by using,python-c"import cowboe"Any error means cowboe was not installed sucessfully.Usagecowboe has different functions which perform individual task like running the cowboe algorithm, performing NM optimization, visualization of the pmf curves and summarizing the NM steps. A detailed explanation and examples with the required data files are provided in the examples directory. A simple but comprehensive example is shown below,fromcowboeimportpmftopoints,cowboe,cowboefit,settings_update
fromcowboeimportcowboeKS,cowboeRNM,cowboeNM,progressfile,NMprogress,cowboe3Dsurface
fromcowboeimportcowboe_wham,pmfcompare,multi_pmfcompare,cowboe_settings,wham_settings
fromcowboeimportcowboe_trajcut,cowboe_OVL,cowboe_pmfplot,pmfdiff
importnumpyasnp
importos
importwarningsos.chdir('location of the examples folder')# uncomment the below two lines if you donot want to see the plot while running from commandline# matplotlib.use('Agg')# warnings.filterwarnings("ignore")# to update the cowboe_setting dictionary.cowboe_settings.update({"param B":2.0})# to convert the rest pmf into array for further processing.'''The below function generates a pickle file called variable.pkl and it will be used for further steps'''pmftopoints(location=os.path.join(loc,'testpmf'),\testpmf='test_pmf.txt',\order=12);# algorithm to get window distribution of the given parameters based on the test pmf data.'''for the initial guess from pmftopoints() the below function runs the cowboe algorithm to itertivelyconstruct windows and generates the samplingtime and forceconstant for each window in order to perform MD runs.''''''Here sc in the below function is the sampling considered in terms of nshere 8ns corresponds to 8ns/window for a total of n number of windowsThe defaults values like the conventional number of windows etc are usedto calculate how much computations the user would have used through the conventionalroutine.And these and other values can be adjusted using dict updatee.g. cowboe_settings.update({"ylim" : (0,16)})'''cowboe(A=3.5000,\B=2.0,\V=0.8000,\sc=8,\name='3',\subtype='100mc',\location=loc+'/temppmf',\equal_sampling=True);# calculates PMF using wham for the given trajectories # must update list.txt which is the metadata file for the wham calculation.# more information on the tool is available here,'''Grossfield, Alan, “WHAM: the weighted histogram analysis method”,version 2.0.10, http://membrane.urmc.rochester.edu/wordpress/?page_id=126''''''All trajectory files must be given a '.traj' extensionlist.txt file should also be present for identifying the trajectory files.This file is same as the metadata file described in the wham documentation,http://membrane.urmc.rochester.edu/wordpress/?page_id=126'''# To update the wham_setting dictionary. This can be used to change the default values.wham_settings.update({"tol":0.00015})cowboe_wham(name='benchmark.txt',location='</cowboe/examples/benchmark>',\MCtrials=0,hist_min=2.0,hist_max=14.5,num_bins=100,tol=0.0001,\temp=298,numpad=0,metadatafile='list.txt')cowboe_wham(name='3.txt',location='</cowboe/examples/3>',\MCtrials=0,hist_min=2.0,hist_max=14.5,num_bins=100,tol=0.0001,\temp=298,numpad=0,metadatafile='list.txt')cowboe_pmfplot(pmf='benchmark.txt',name='benchmark')cowboe_pmfplot(pmf='3.txt',name='3')'''To plot two PMf curves and get their absolute difference.'''pmfdiff(pmf1='benchmark.txt',pmf2='3.txt',name='benchmark-3-diff')'''To compare multiple PMF curve by plotting them together'''pmfcompare(pmfs=['benchmark.txt','3.txt'],name='comparison_benchmark_3',splices=[8,10],lloc='outside',markzero=False)'''To calculate the fitness of a test case w.r.t to the benchmark case.'''cowboefit(test='3.txt',bench='benchmark.txt',frommin=False)'''We need three initial parameter combinations to run the NM algorithmHere the three initial guess are 1,2,3..We can compare the pmf curves using the below functions''''''# A, V, max_vdist or fit() values for the three pointsA = [2.0, 2.9, 3.5]V = [0.75, 0.8700, 0.8000]fit = [1.9834, 1.3844, 4.7587]# Gives the possible moves with (R)NM algorithm for the above defined simplex.cowboeNM(A = A, V = V, fit = fit)cowboeRNM(A = A, V = V, fit = fit)'''Afteraseriesof(R)NMsteps,theuserwillhaveasetofsubsequentsimplexes
eachofwhichwillbea1*3*3array,sayifwehave6steps,wewillhavea6*3*3array'''p = np.array(   [[[2.    , 0.75  , 1.9943],[2.9   , 0.87  , 1.8232],[3.5   , 0.8   , 4.7636]],[[2.    , 0.75  , 1.9943],[2.9   , 0.87  , 1.8232],[1.6571, 0.82  , 0.9899]],[[2.4028, 0.94  , 2.0045],[2.9   , 0.87  , 1.8232],[1.6571, 0.82  , 0.9899]],[[2.0939, 0.7975, 1.4695],[2.9   , 0.87  , 1.8232],[1.6571, 0.82  , 0.9899]],[[2.0939, 0.7975, 1.4695],[1.1965, 0.7475, 3.5148],[1.6571, 0.82  , 0.9899]],[[2.0939, 0.7975, 1.4695],[2.3242, 0.8394, 1.8202],[1.6571, 0.82  , 0.9899]]])'''Thebelowfunctionwritesatextfilecalledprogress.txtwhichsummarizesthestepsinacleanformat.'''progressfile(points=p)'''ThebelowfunctionplotsthedifferentNMstepsandsummarizesthemasagif'''NMprogress(progressfile = 'progress.txt')'''Thebelowfunctioncreatesa3dsurfaceoftheparamaterspaceusingthedifferentparameterevaluations,inordertheusethisfunctoinffmpegmustbeinstalledinthepath

Moreinformationonthisisavailablehere,

https://www.ffmpeg.org/
https://www.ffmpeg.org/download.html
https://anaconda.org/conda-forge/ffmpeg'''cowboe3Dsurface(progressfile = 'progress.txt')'''Thefollowingfunctionsareallusedformodifyingortestingthetrajectoryfilesandothersamplingrelatedproperties.'''cowboe_trajcut(percentage=50.0, location='</cowboe/examples/benchmark>',\name='benchmark',listfile='list.txt',start=0)'''TodocomputetheKolmogorov-Smirnovstatisticon2samples.
Thenullhypothesisisthatthetwoindividualsampleswereextractedfromthesamedistribution
andifthep-valueislargeortheKSstatisticsissmall,thenwecannotrejectthehypothesisthatthedistributionsofthetwosamplesarethesame.'''cowboeKS(location='</cowboe/examples/benchmark>', \listfile='list.txt', percentage = 85)'''Tocalculatethecoefficientofoverlap(OVL)fordifferentwindow's distribution'''cowboe_OVL(location='</cowboe/examples/benchmark>',\listfile='list.txt',name='benchmark',distplot=False)'''On calling the below function, details on default setting and ways to modify them will be shown'''settings_update()## Nelder-Mead simplex algorithmTheprimarydifferencebetweentheNMandrestrictedNMisthattheRNMdoesntincludetheexpansionstepafterreflection.ThecowboeNMandcowboeRNMprovidepossibleNMstepsforagivensimplexandtheuserwouldselectastepbasedonthebelowpseudocode.`PseudocodeoftheSimplexNelder-MeadOptimization`Initializethesimplexwithn-1randomstartingparametervaluecombinationse.g.[A,V],wherenisthenumberofparametersbeingoptimized.Nelder-Meadalgorithm:whileloopnotdonecalculatecentroidcalculatereflectedifreflectedisbetterthanbestsolutionthencalculateexpandedreplaceworstsolutionwithbetterofreflectedandexpandedelseifreflectedisworsethanallbutworstthencalculateoutwardcontractedifoutwardcontractedisbetterthanreflectedreplaceworstsolutionwithoutwardcontractedendifelseshrinkthesearchareaelseifreflectedisworsethanallcalculateinwardcontractedifinwardcontractedisbetterthanworstreplaceworstsolutionwithinwardcontractedendifelseshrinkthesearchareaelsereplaceworstsolutionwithreflectedendififthesolutioniswithintolerance,exitloopendloopreturnbestsolutionfound

cowboeandtheWHAMwrapperhavebeengivendefaultsvalueswhichcanbemodifiedbychangingthecowboe.pyfileintheinstallationlocationortomaketemporarychangesdictupdate()ofcanbeusedasshownabove.Moreinformationonthiscanbeobtainedbycallingthesettings_update()functionincowboe.## LicenseGNUGeneralPublicLicensev3.0