Package: pyspa
pyspais an object-orientedpythonpackage which enables you to conduct a parametric structural path analysis on square A matrices (process or input-output) for any number of environmental, social or economic satellites/flows and for any number of stages upstream in your supply chain (as long you have enough RAM). The package produces a SupplyChain object which includes Pathway and Node objects (among others). Results can be exported to the csv format with a single line of code.The concept behindpyspawas driven by the lack of open source code to conduct structural path analysis in a robust and object-oriented manner.Getting StartedPrerequisitesYou will needpythonto run this package as well as the following python packages:numpypandasscipy- To support the use of sparse A matricesInstallingDownload and install the package from pippip install pyspaTesting pyspaIdentify the template files in the installed directory, or download them directly from thegithub repository. The template files include:A_matrix_template.csvInfosheet_template.csvThresholds_template.csvThresholds_template_perc.csvOnce you have located these files,you need to run a single functionthat will read the data, conduct the structural path analysis and return a SupplyChain object, as per the following code.sc = pyspa.get_spa(target_ID = 70, max_stage = 10, a_matrix ='A_matrix_template.csv', infosheet='Infosheet_template.csv', thresholds='Thresholds_template.csv')This will return your SupplyChain object which has numerous methods. Read thedocumentationfor more information.Note that from pyspa 2.0 forward, this will also, by default, breakdown the remainder of the supply chain (not covered by your spa) into remainder pathways.
You can also provide the thresholds as percentages of the total value, which is more convenient. To do so, simply use the call:sc = pyspa.get_spa(target_ID = 70, max_stage = 10, a_matrix ='A_matrix_template.csv', infosheet='Infosheet_template.csv', thresholds='Thresholds_template_perc.csv', thresholds_as_percentages=True)To export the structural path analysis to acsvfile, use the built-in method.sc.export_to_csv('spa_results.csv')Tosaveyour SupplyChain object and avoid having to recalculate everything (this uses pickle):sc.save('supply_chain.sc')Toloada previously saved SupplyChain object:loaded_sc = pyspa.load_instance_from_file('supply_chain.sc', pyspa.SupplyChain)We have developped the required python methods on each object so that you cancomparethem. Thus,sc == loaded_scorsc.pathways_list[-1] == loaded_sc.pathways_list[-1]orsc.root_node == loaded_sc.root_nodewill returnTrue.Thedetailed documentationis availablehereInput filesDescriptionThe package requires three csv files to be able to conduct a structural path analysis:Asquaretechnological matrix, aka an A matrixAn infosheet listing all sectors or processes, along with the direct and total intensities/multipliers/requirements for any number of environmental/economic/social satellites, and their metadataThe cut-off thresholds used to trim the supply chain branches for each satellite. These can be provided either as absolute values or as percentages of the total intensity of the target sector/process.These csv files must be formatted in a certain way for the code to work. The formatting requirements are described below.FormattingSquare technological matrix (A matrix)The A matrix should be provided in a single csv file, regardless of its size (we have tried the code on 15kÃ—15k matrix so far, and it works fine). It must be formatted as follows:The top row must be the indexes of the sectors/processes, numbered from 1 to n.The rest of the matrix comes underneath that row.No text headers nor text contentPreview of A matrix csv layout â†“1...n<A matrix: input from 1 into 1><A matrix: input from 1 into ...><A matrix: input from 1 into n><A matrix: input from ... into 1><A matrix: input from ... into ...><A matrix: input from ... into n><A matrix: input from n into 1><A matrix: input from n into ...><A matrix: input from n into n>InfosheetThe infosheet must contain mandatory columns and at least one environmental/social/economic satellite/flow. It must be formatted as follows (all headers are case sensitive):Thefirst columnhas a header called"Sector ID"and contains the IDs of each sector/process from 1 to n. These IDs match those included as a header in theA matrix.Thesecond columnhas a header called"Name"and contains the name of each sector/process. It is highly recommended to have unique names as the csv output of the package uses names (not IDs).Thethird columnhas a header called"Unit"and contains the functional unit of each sector/process. It is usually a financial currency for input-output sectors (e.g. AUD, USD, EUR, YEN, etc.) and can be a physical unit for processes (e.g. kg, mÂ³, tkm, etc.).Thefourth columnhas a header called"Region"and contains the region of each sector processs. If you are not working with multiregional data, simply populate this column with the name of the region for your data (for instance in the template file, the region for all sectors is"Australia".From thefifth columnonwards you need to include at least one satellite/flow. Satellites/flows are included usingtwo columns:
+The first column contains the direct intensity/multiplier/requirement for your satellite/flow and has a header in the following format:DR_<satellite/flow_name>_(<satellite/flow_unit>)For example, for greenhouse gas emissions, you can write:DR_GHGe_(kgCO2e)+The second column contains the total intensity/multiplier/requirement for your satellite/flow and has a header in the following format:TR_<satellite/flow_name>_(<satellite/flow_unit>)For example, for greenhouse gas emissions, you can write:TR_GHGe_(kgCO2e)You can add as many satellites as you need to the infosheet. The code will detect them automatically, as long as their headers are formatted as above.
You can also add any other metadata column for your sectors/processes, and then access them through manual coding using the predefined method on yourNodeobjects:get_node_attribute. See thedetailed documentationfor more details.ThresholdsThe thresholds csv is by far the simplest csv file to provide. It contains onlytwo columnsand must be formatted as below:Thefirst columnhas a header called"Flow"which contains the name of each satellite/flow that you are using, e.g. GHGe. The name of the satellite/flow must be exactly the same as what is contained in the DR and TR headers of the infosheet, but without theDR/TR_prefix and without the_(<satellite/flow_unit>)suffix.Thesecond columnhas a header called"Value"which contains the threshold value of each satellite/flow that you are using, e.g. GHGe.
Two options are available for the"Value"field:If you use absolute values is usually very low. For common environmental satellites/flows, such as water(kL), energy(GJ) and greenhouse gas emissions(kgCO2e), we use threshold values for input-output data in the range of 0.000 1 and 0.000 000 000 1. The lower the threshold, the more supply chain nodes you consider, the longer the structural path analysis will take.If you use relative values (i.e. percentages of the total intensity of you target sector/process), you simply enter the percentage to be used, e.g. for 0.1%, enter 0.1.CSV output fileThe csv output file contains some metadata on the structural path analysis itself and then lists, for each satellite/flow, the pathways extracted, by order of significance in terms of the direct intensity/multiplier/requirement of the last node in that pathway. The columns for these listing are:The percentage of contribution of that last node in that pathway, to the total intensity/multiplier/requirement of the selected sector/process is providedThe value of the corresponding direct intensity/multiplier/requirementThe value of the corresponding total intensity/multiplier/requirementThe name of each node in the pathway, for each stage of the supply chain (1 to n).The direct intensity/multiplier/requirement of the selected sector/process is referred to asDIRECT (Stage 0).Stage 1refers to the first stage upstream in the supply chain,Stage 2the following stage, all the way toStage mas selected at the start. We recommend using around10 stagesupstream for process data, and8 stagesupstream for input-output data, based on our experience. But these values might differ.
Remainder pathways are appended at the end of the spa and broken down across the supply chain, identifying clearly where the thresholds were used to cut-off pathways that did not meet the threshold criteria.Note: The results for each satellite/flow are listed on the same csv sheet, in the order the appear in the infosheet. You will need to scroll down to identify where each new satellite/flow results starts, which is indicated by a header and an empty row. For those using Windows, you can click on any pathway for any given satellite/flow and press: "Ctrl + Shift + â†“". This will take you to the last pathway for this satellite/flow.Other ways to call pyspa.get_spa()You can also call pyspa.get_spa using objects in the RAM instead of csv files. That is, a numpy array or scipy sparse array for the A matrix, and dictionaries for the infosheet and thresholds. You can also mix and match between objects in the RAM and csv files, for addtitional flexibility.Built with:pycharmsourcetreeSweat, tears, Belgian beers, and coffee from Castro'sAuthors and contributorsAuthorsAndrÃ© Stephan-overall design, implementation, testing and debugging-ORCIDPaul-Antoine Bontinck-optimisation, implementation, testing and debugging-ORCIDContributorsRobert H Crawford-project leader and theoretical guidance-ORCIDFabian Prideaux-proof reading documentation, testing package installationLicenseThis project is shared under a GNU General Public License v3.0. See theLICENSEfile for more information.AcknowledgmentsThis project was originally funded by theAustralian Research Council Discovery Project DP150100962at theUniversity of Melbourne, Australia. As such, we are endebted to Australian taxpayers for making this work possible and to the University of Melbourne for providing the facilities and intellectual space to conduct this research. The code for the base method for conducting the structural path analysis is inspired from the code of lateA/Prof Graham Treloarat the University of Melbourne, who pioneered a Visual Basic Script in hisPhD thesisto conduct a structural path analysis in 1997.