<SYSTEM_TASK:>
Given the following text description, write Python code to implement the functionality described below step by step
<END_TASK>
<USER_TASK:>
Description:
 Symca
Symca is used to perform symbolic metabolic control analysis [3,4] on metabolic pathway models in order to dissect the control properties of these pathways in terms of the different chains of local effects (or control patterns) that make up the total control coefficient values. Symbolic/algebraic expressions are generated for each control coefficient in a pathway which can be subjected to further analysis.
Features
Generates symbolic expressions for each control coefficient of a metabolic pathway model. 
Splits control coefficients into control patterns that indicate the contribution of different chains of local effects.
Control coefficient and control pattern expressions can be manipulated using standard SymPy functionality. 
Values of control coefficient and control pattern values are determined automatically and updated automatically following the calculation of standard (non-symbolic) control coefficient values subsequent to a parameter alteration.
Analysis sessions (raw expression data) can be saved to disk for later use. 
The effect of parameter scans on control coefficient and control patters can be generated and displayed using ScanFig.
Visualisation of control patterns by using ModelGraph functionality.
Saving/loading of Symca sessions.
Saving of control pattern results.
Usage and feature walkthrough
Workflow
Performing symbolic control analysis with Symca usually requires the following steps
Step1:  Additionally Symca has the following arguments
Step2:  do_symca has the following arguments
Step3:  Inspecting an individual control coefficient yields a symbolic expression together with a value
Step4:  In the above example, the expression of the control coefficient consists of two numerator terms and a common denominator shared by all the control coefficient expression signified by $\Sigma$.
Various properties of this control coefficient can be accessed such as the
Step5:  Numerator expression (as a SymPy expression)
Step6:  Denominator expression (as a SymPy expression)
Step7:  Value (as a float64)
Step8:  Additional, less pertinent, attributes are abs_value, latex_expression, latex_expression_full, latex_numerator, latex_name, name and denominator_object.
The individual control coefficient numerator terms, otherwise known as control patterns, may also be accessed as follows
Step9:  Each control pattern is numbered arbitrarily starting from 001 and has similar properties as the control coefficient object (i.e., their expression, numerator, value etc. can also be accessed).
Control pattern percentage contribution
Additionally control patterns have a percentage field which indicates the degree to which a particular control pattern contributes towards the overall control coefficient value
Step10:  Unlike conventional percentages, however, these values are calculated as percentage contribution towards the sum of the absolute values of all the control coefficients (rather than as the percentage of the total control coefficient value). This is done to account for situations where control pattern values have different signs.
A particularly problematic example of where the above method is necessary, is a hypothetical control coefficient with a value of zero, but with two control patterns with equal value but opposite signs. In this case a conventional percentage calculation would lead to an undefined (NaN) result, whereas our methodology would indicate that each control pattern is equally ($50\%$) responsible for the observed control coefficient value.
Dynamic value updating
The values of the control coefficients and their control patterns are automatically updated when new steady-state
elasticity coefficients are calculated for the model. Thus changing a parameter of lin4_hill, such as the $V_{f}$ value of reaction 4, will lead to new control coefficient and control pattern values
Step11:  Control pattern graphs
As described under Basic Usage, Symca has the functionality to display the chains of local effects represented by control patterns on a scheme of a metabolic model. This functionality can be accessed via the highlight_patterns method
Step12:  highlight_patterns has the following optional arguments
Step13:  Parameter scans
Parameter scans can be performed in order to determine the effect of a parameter change on either the control coefficient and control pattern values or of the effect of a parameter change on the contribution of the control patterns towards the control coefficient (as discussed above). The procedures for both the "value" and "percentage" scans are very much the same and rely on the same principles as described in the Basic Usage and RateChar sections.
To perform a parameter scan the do_par_scan method is called. This method has the following arguments
Step14:  As previously described, these data can be displayed using ScanFig by calling the plot method of percentage_scan_data. Furthermore, lines can be enabled/disabled using the toggle_category method of ScanFig or by clicking on the appropriate buttons
Step15:  A value plot can similarly be generated and displayed. In this case, however, an additional line indicating $C^{J}_{4}$ will also be present
Step16:  Fixed internal metabolites
In the case where the concentration of an internal intermediate is fixed (such as in the case of a GSDA) the internal_fixed argument must be set to True in either the do_symca method, or when instantiating the Symca object. This will typically result in the creation of a cc_results_N object for each separate reaction block, where N is a number starting at 0. Results can then be accessed via these objects as with normal free internal intermediate models.
Thus for a variant of the lin4_fb model where the intermediateS3 is fixed at its steady-state value the procedure is as follows
Step17:  The normal sc_fixed_S3.cc_results object is still generated, but will be invalid for the fixed model. Each additional cc_results_N contains control coefficient expressions that have the same common denominator and corresponds to a specific reaction block. These cc_results_N objects are numbered arbitrarily, but consistantly accross different sessions. Each results object accessed and utilised in the same way as the normal cc_results object. 
For the mod_fixed_c model two additional results objects (cc_results_0 and cc_results_1) are generated
Step18:  cc_results_0 contains the control coefficients describing the sensitivity of flux and concentrations of either reaction block towards reactions in the other reaction block (i.e., all control coefficients here should be zero). Due to the fact that the S3 demand block consists of a single reaction, this object also contains the control coefficient of R4 on J_R4, which is equal to one. This results object is useful confirming that the results were generated as expected.
Step19:  If the demand block of S3 in this pathway consisted of multiple reactions, rather than a single reaction, there would have been an additional cc_results_N object containing the control coefficients of that reaction block.  
Saving results
In addition to being able to save parameter scan results (as previously described), a summary of the control coefficient and control pattern results can be saved using the save_results method. This saves a csv file (by default) to disk to any specified location. If no location is specified, a file named cc_summary_N is saved to the ~/Pysces/$modelname/symca/ directory, where N is a number starting at 0
Step20:  save_results has the following optional arguments
Step21:  Saving/loading sessions
Saving and loading Symca sessions is very simple and works similar to RateChar. Saving a session takes place with the save_session method, whereas the load_session method loads the saved expressions. As with the save_results method and most other saving and loading functionality, if no file_name argument is provided, files will be saved to the default directory (see also Basic Usage). As previously described, expressions can also automatically be loaded/saved by do_symca by using the auto_save_load argument which saves and loads using the default path. Models with internal fixed metabolites are handled automatically.
<ASSISTANT_TASK:>
Python Code:
mod = pysces.model('lin4_fb')
sc = psctb.Symca(mod)
Explanation: Symca
Symca is used to perform symbolic metabolic control analysis [3,4] on metabolic pathway models in order to dissect the control properties of these pathways in terms of the different chains of local effects (or control patterns) that make up the total control coefficient values. Symbolic/algebraic expressions are generated for each control coefficient in a pathway which can be subjected to further analysis.
Features
Generates symbolic expressions for each control coefficient of a metabolic pathway model. 
Splits control coefficients into control patterns that indicate the contribution of different chains of local effects.
Control coefficient and control pattern expressions can be manipulated using standard SymPy functionality. 
Values of control coefficient and control pattern values are determined automatically and updated automatically following the calculation of standard (non-symbolic) control coefficient values subsequent to a parameter alteration.
Analysis sessions (raw expression data) can be saved to disk for later use. 
The effect of parameter scans on control coefficient and control patters can be generated and displayed using ScanFig.
Visualisation of control patterns by using ModelGraph functionality.
Saving/loading of Symca sessions.
Saving of control pattern results.
Usage and feature walkthrough
Workflow
Performing symbolic control analysis with Symca usually requires the following steps:
Instantiation of a Symca object using a PySCeS model object.
Generation of symbolic control coefficient expressions.
Access generated control coefficient expression results via cc_results and the corresponding control coefficient name (see Basic Usage)
Inspection of control coefficient values.
Inspection of control pattern values and their contributions towards the total control coefficient values. 
Inspection of the effect of parameter changes (parameter scans) on the values of control coefficients and control patterns and the contribution of control patterns towards control coefficients.
Session/result saving if required
Further analysis.
Object instantiation
Instantiation of a Symca analysis object requires PySCeS model object (PysMod) as an argument. Using the included lin4_fb.psc model a Symca session is instantiated as follows:
End of explanation
sc.do_symca()
Explanation: Additionally Symca has the following arguments:
internal_fixed: This must be set to True in the case where an internal metabolite has a fixed concentration (default: False)
auto_load: If True Symca will try to load a previously saved session. Saved data is unaffected by the internal_fixed argument above (default: False).
.. note:: For the case where an internal metabolite is fixed see Fixed internal metabolites below.
Generating symbolic control coefficient expressions
Control coefficient expressions can be generated as soon as a Symca object has been instantiated using the do_symca method. This process can potentially take quite some time to complete, therefore we recommend saving the generated expressions for later loading (see Saving/Loading Sessions below). In the case of lin4_fb.psc expressions should be generated within a few seconds.
End of explanation
sc.cc_results
Explanation: do_symca has the following arguments:
internal_fixed: This must be set to True in the case where an internal metabolite has a fixed concentration (default: False)
auto_save_load: If set to True Symca will attempt to load a previously saved session and only generate new expressions in case of a failure. After generation of new results, these results will be saved instead. Setting internal_fixed to True does not affect previously saved results that were generated with this argument set to False (default: False).
Accessing control coefficient expressions
Generated results may be accessed via a dictionary-like cc_results object (see Basic Usage - Tables). Inspecting this cc_results object in a IPython/Jupyter notebook yields a table of control coefficient values:
End of explanation
sc.cc_results.ccJR1_R4
Explanation: Inspecting an individual control coefficient yields a symbolic expression together with a value:
End of explanation
sc.cc_results.ccJR1_R4.expression
Explanation: In the above example, the expression of the control coefficient consists of two numerator terms and a common denominator shared by all the control coefficient expression signified by $\Sigma$.
Various properties of this control coefficient can be accessed such as the:
* Expression (as a SymPy expression)
End of explanation
sc.cc_results.ccJR1_R4.numerator
Explanation: Numerator expression (as a SymPy expression)
End of explanation
sc.cc_results.ccJR1_R4.denominator
Explanation: Denominator expression (as a SymPy expression)
End of explanation
sc.cc_results.ccJR1_R4.value
Explanation: Value (as a float64)
End of explanation
sc.cc_results.ccJR1_R4.CP001
sc.cc_results.ccJR1_R4.CP002
Explanation: Additional, less pertinent, attributes are abs_value, latex_expression, latex_expression_full, latex_numerator, latex_name, name and denominator_object.
The individual control coefficient numerator terms, otherwise known as control patterns, may also be accessed as follows:
End of explanation
sc.cc_results.ccJR1_R4.CP001.percentage
sc.cc_results.ccJR1_R4.CP002.percentage
Explanation: Each control pattern is numbered arbitrarily starting from 001 and has similar properties as the control coefficient object (i.e., their expression, numerator, value etc. can also be accessed).
Control pattern percentage contribution
Additionally control patterns have a percentage field which indicates the degree to which a particular control pattern contributes towards the overall control coefficient value:
End of explanation
mod.reLoad()
# mod.Vf_4 has a default value of 50
mod.Vf_4 = 0.1
# calculating new steady state
mod.doMca()
# now ccJR1_R4 and its two control patterns should have new values
sc.cc_results.ccJR1_R4
# original value was 0.000
sc.cc_results.ccJR1_R4.CP001
# original value was 0.964
sc.cc_results.ccJR1_R4.CP002
# resetting to default Vf_4 value and recalculating
mod.reLoad()
mod.doMca()
Explanation: Unlike conventional percentages, however, these values are calculated as percentage contribution towards the sum of the absolute values of all the control coefficients (rather than as the percentage of the total control coefficient value). This is done to account for situations where control pattern values have different signs.
A particularly problematic example of where the above method is necessary, is a hypothetical control coefficient with a value of zero, but with two control patterns with equal value but opposite signs. In this case a conventional percentage calculation would lead to an undefined (NaN) result, whereas our methodology would indicate that each control pattern is equally ($50\%$) responsible for the observed control coefficient value.
Dynamic value updating
The values of the control coefficients and their control patterns are automatically updated when new steady-state
elasticity coefficients are calculated for the model. Thus changing a parameter of lin4_hill, such as the $V_{f}$ value of reaction 4, will lead to new control coefficient and control pattern values:
End of explanation
# This path leads to the provided layout file 
path_to_layout = '~/Pysces/psc/lin4_fb.dict'
# Correct path depending on platform - necessary for platform independent scripts
if platform == 'win32' and pysces.version.current_version_tuple() < (0,9,8):
    path_to_layout = psctb.utils.misc.unix_to_windows_path(path_to_layout)
else:
    path_to_layout = path.expanduser(path_to_layout)
sc.cc_results.ccJR1_R4.highlight_patterns(height = 350, pos_dic=path_to_layout)
Explanation: Control pattern graphs
As described under Basic Usage, Symca has the functionality to display the chains of local effects represented by control patterns on a scheme of a metabolic model. This functionality can be accessed via the highlight_patterns method:
End of explanation
# clicking on CP002 shows that this control pattern representing 
# the chain of effects passing through the feedback loop
# is totally responsible for the observed control coefficient value.
sc.cc_results.ccJR1_R4.highlight_patterns(height = 350, pos_dic=path_to_layout)
# clicking on CP001 shows that this control pattern representing 
# the chain of effects of the main pathway does not contribute
# at all to the control coefficient value.
sc.cc_results.ccJR1_R4.highlight_patterns(height = 350, pos_dic=path_to_layout)
Explanation: highlight_patterns has the following optional arguments:
width: Sets the width of the graph (default: 900).
height:Sets the height of the graph (default: 500).
show_dummy_sinks: If True reactants with the "dummy" or "sink" will not be displayed (default: False).
show_external_modifier_links: If True edges representing the interaction of external effectors with reactions will be shown (default: False).
Clicking either of the two buttons representing the control patterns highlights these patterns according according to their percentage contribution (as discussed above) towards the total control coefficient.
End of explanation
percentage_scan_data = sc.cc_results.ccJR1_R4.do_par_scan(parameter='Vf_4',
                                                          scan_range=numpy.logspace(-1,3,200),
                                                          scan_type='percentage')
Explanation: Parameter scans
Parameter scans can be performed in order to determine the effect of a parameter change on either the control coefficient and control pattern values or of the effect of a parameter change on the contribution of the control patterns towards the control coefficient (as discussed above). The procedures for both the "value" and "percentage" scans are very much the same and rely on the same principles as described in the Basic Usage and RateChar sections.
To perform a parameter scan the do_par_scan method is called. This method has the following arguments:
parameter: A String representing the parameter which should be varied.
scan_range: Any iterable representing the range of values over which to vary the parameter (typically a NumPy ndarray generated by numpy.linspace or numpy.logspace).
scan_type: Either "percentage" or "value" as described above (default: "percentage").
init_return: If True the parameter value will be reset to its initial value after performing the parameter scan (default: True).
par_scan: If True, the parameter scan will be performed by multiple parallel processes rather than a single process, thus speeding performance (default: False).
par_engine: Specifies the engine to be used for the parallel scanning processes. Can either be "multiproc" or "ipcluster". A discussion of the differences between these methods are beyond the scope of this document, see here for a brief overview of Multiprocessing in Python. (default: "multiproc").
force_legacy: If True do_par_scan will use a older and slower algorithm for performing the parameter scan. This is mostly used for debugging purposes. (default: False)
Below we will perform a percentage scan of $V_{f4}$ for 200 points between 0.01 and 1000 in log space:
End of explanation
percentage_scan_plot = percentage_scan_data.plot()
# set the x-axis to a log scale
percentage_scan_plot.ax.semilogx()
# enable all the lines
percentage_scan_plot.toggle_category('Control Patterns', True)
percentage_scan_plot.toggle_category('CP001', True)
percentage_scan_plot.toggle_category('CP002', True)
# display the plot
percentage_scan_plot.interact()
Explanation: As previously described, these data can be displayed using ScanFig by calling the plot method of percentage_scan_data. Furthermore, lines can be enabled/disabled using the toggle_category method of ScanFig or by clicking on the appropriate buttons:
End of explanation
value_scan_data = sc.cc_results.ccJR1_R4.do_par_scan(parameter='Vf_4',
                                                     scan_range=numpy.logspace(-1,3,200),
                                                     scan_type='value')
value_scan_plot = value_scan_data.plot()
# set the x-axis to a log scale
value_scan_plot.ax.semilogx()
# enable all the lines
value_scan_plot.toggle_category('Control Coefficients', True)
value_scan_plot.toggle_category('ccJR1_R4', True)
value_scan_plot.toggle_category('Control Patterns', True)
value_scan_plot.toggle_category('CP001', True)
value_scan_plot.toggle_category('CP002', True)
# display the plot
value_scan_plot.interact()
Explanation: A value plot can similarly be generated and displayed. In this case, however, an additional line indicating $C^{J}_{4}$ will also be present:
End of explanation
# Create a variant of mod with 'C' fixed at its steady-state value
mod_fixed_S3 = psctb.modeltools.fix_metabolite_ss(mod, 'S3')
# Instantiate Symca object the 'internal_fixed' argument set to 'True'
sc_fixed_S3 = psctb.Symca(mod_fixed_S3,internal_fixed=True)
# Run the 'do_symca' method (internal_fixed can also be set to 'True' here)
sc_fixed_S3.do_symca() 
Explanation: Fixed internal metabolites
In the case where the concentration of an internal intermediate is fixed (such as in the case of a GSDA) the internal_fixed argument must be set to True in either the do_symca method, or when instantiating the Symca object. This will typically result in the creation of a cc_results_N object for each separate reaction block, where N is a number starting at 0. Results can then be accessed via these objects as with normal free internal intermediate models.
Thus for a variant of the lin4_fb model where the intermediateS3 is fixed at its steady-state value the procedure is as follows:
End of explanation
sc_fixed_S3.cc_results_1
Explanation: The normal sc_fixed_S3.cc_results object is still generated, but will be invalid for the fixed model. Each additional cc_results_N contains control coefficient expressions that have the same common denominator and corresponds to a specific reaction block. These cc_results_N objects are numbered arbitrarily, but consistantly accross different sessions. Each results object accessed and utilised in the same way as the normal cc_results object. 
For the mod_fixed_c model two additional results objects (cc_results_0 and cc_results_1) are generated:
cc_results_1 contains the control coefficients describing the sensitivity of flux and concentrations within the supply block of S3 towards reactions within the supply block.
End of explanation
sc_fixed_S3.cc_results_0
Explanation: cc_results_0 contains the control coefficients describing the sensitivity of flux and concentrations of either reaction block towards reactions in the other reaction block (i.e., all control coefficients here should be zero). Due to the fact that the S3 demand block consists of a single reaction, this object also contains the control coefficient of R4 on J_R4, which is equal to one. This results object is useful confirming that the results were generated as expected.
End of explanation
sc.save_results()
Explanation: If the demand block of S3 in this pathway consisted of multiple reactions, rather than a single reaction, there would have been an additional cc_results_N object containing the control coefficients of that reaction block.  
Saving results
In addition to being able to save parameter scan results (as previously described), a summary of the control coefficient and control pattern results can be saved using the save_results method. This saves a csv file (by default) to disk to any specified location. If no location is specified, a file named cc_summary_N is saved to the ~/Pysces/$modelname/symca/ directory, where N is a number starting at 0:
End of explanation
# the following code requires `pandas` to run
import pandas as pd
# load csv file at default path
results_path = '~/Pysces/lin4_fb/symca/cc_summary_0.csv'
# Correct path depending on platform - necessary for platform independent scripts
if platform == 'win32' and pysces.version.current_version_tuple() < (0,9,8):
    results_path = psctb.utils.misc.unix_to_windows_path(results_path)
else:
    results_path = path.expanduser(results_path)
saved_results = pd.read_csv(results_path)
# show first 20 lines
saved_results.head(n=20) 
Explanation: save_results has the following optional arguments:
file_name: Specifies a path to save the results to. If None, the path defaults as described above.
separator: The separator between fields (default: ",")
The contents of the saved data file is as follows:
End of explanation
# saving session
sc.save_session()
# create new Symca object and load saved results
new_sc = psctb.Symca(mod)
new_sc.load_session()
# display saved results
new_sc.cc_results
Explanation: Saving/loading sessions
Saving and loading Symca sessions is very simple and works similar to RateChar. Saving a session takes place with the save_session method, whereas the load_session method loads the saved expressions. As with the save_results method and most other saving and loading functionality, if no file_name argument is provided, files will be saved to the default directory (see also Basic Usage). As previously described, expressions can also automatically be loaded/saved by do_symca by using the auto_save_load argument which saves and loads using the default path. Models with internal fixed metabolites are handled automatically.
End of explanation
<END_TASK>