Package: python-AGS4
python-ags4[[TOC]]Introductionpython-ags4is a library of functions thatimports/readsAGS4files to a collection ofPandas DataFrames.data can be analyzed, manipulated, and updated using Pandasand then exported/written back to an AGS4 fileRelease available atpypi.org/project/python-ags4/This project is maintained by theAGS Data Format Working GroupNoteThis repo was forked fromgithub.com/asitha-sena/python-ags4which is now archived and read-onlyHEAD isgitlab.com/ags-data-format-wg/ags-python-libraryDocumentationInstallationpipinstallpython-ags4NoteInstallation requires Python 3.8 or later.Code ExamplesFirst import the module.frompython_ags4importAGS4Import data from an AGS4 file# Load from a filetables,headings=AGS4.AGS4_to_dataframe('path/to/file.ags')# Or use our sample datafrompython_ags4.dataimportload_test_datatables,headings=load_test_data()tablesis a dictionary of Pandas DataFrames. Each DataFrame contains the data from aGROUPin the AGS4 file.headingsis a dictionary of lists. Each list has the header names of the correspondingGROUPImportant:If the above code throws an exception or returns an empty dictionary, it very likely that the input file is not a valid AGS4 file. In such a case, theAGS4.check_file()function can be used to validate the file and see whether anything needs to be fixed before trying again. Most users will find it easier perform this step using thecommand line interfaceas it will provide a formatted error report that is much easier to read than the python dictionary created by directly calling the function.All data are imported as text so they cannot be analyzed or plotted immediately. You can use the following code to convert all the numerical data in a DataFrame from text to numeric.LOCA=AGS4.convert_to_numeric(tables['LOCA'])TheAGS4.convert_to_numeric()function automatically converts all columns in the input DataFrame with the a numericTYPEto a float. (Note: The UNIT and TYPE rows are removed during this operation as they are non-numeric.)Export data back to an AGS4 fileAGS4.dataframe_to_AGS4(tables,headings,'output.ags')A DataFrame with numeric columns may not get exported with the correct precision so they should be converted back to formatted text. TheAGS4.convert_to_text()function will do this automatically if an AGS4 dictionary file is provided with the necessary UNIT and TYPE information. Numeric fields in the DataFrame that are not described in the dictionary file will be skipped with a warning.LOCA_txt=AGS4.convert_to_text(LOCA,'DICT.ags')Tables converted to numeric using theAGS4.convert_to_numeric()function should always be converted back to text before exporting to an AGS4 file. (Note: The UNIT and TYPE rows will be added back in addition to formatting the numeric columns.)Juypter NotebookWe have created an example Juypter Notebook which imports an AGS file, plots boreholes on a map and creates a Striplog.See hereCommand Line InterfaceA cli tool was added in version 0.2.0. It should be available from the terminal (or on the Anaconda Powershell prompt in Windows) after runningpython pip install python-ags4>=0.2.0It does not yet have the full functionality of the library, but it does provide a quick and easy way to convert .ags files to Excel spreadsheets (.xlsx) and back. The data can be easily edited in a spreadsheet and then converted back a .ags file. The TYPE values for numeric columns can be changed in the spreadsheet and the data will be automatically reformatted correctly when converted back to .ags, as long as all values in a column are numbers. Any supposedly numeric columns with text entries will be skipped with a warning message.(Note: All data is imported to the spreadsheet as text entries so any column that should be reformatted should be explicitly converted to numbers in Excel.)A checking tool is available as of version 0.3.0 and it can be used to make sure that the file conforms to the AGS4 rules. The tool has been tested in both bash and Powershell.Graphical User Interface usingpandasguiThe output frompython-ags4can be directly used withpandasguito view and edit AGS4 files using an interactive graphical user interface. It also provides funtionality to plot and visualize the data.frompandasguiimportshowfrompython_ags4.dataimportload_test_datatables,headings=load_test_data()gui=show(**tables)Any edits made in the GUI can be saved and exported back to an AGS4 file as follows:updated_tables=gui.get_dataframes()AGS4.dataframe_to_AGS4(updated_tables,headings,'output.ags')DevelopmentPlease refer to theWikipage for details about the development environment and how to get involved in the project.API documentation available athttps://ags-data-format-wg.gitlab.io/ags-python-libraryCitationSenanayake et al., (2022). python-ags4: A Python library to read, write, and validate AGS4 geodata files. Journal of Open Source Software, 7(79), 4569,https://doi.org/10.21105/joss.04569ImplementationsThis library has been used to createWindows Desktop Application -https://gitlab.com/ags-data-format-wg/ags-checker-desktop-appWeb application and API (pyagsapi) -https://github.com/BritishGeologicalSurvey/pyagsapiDeployed ashttps://agsapi.bgs.ac.uk/Excel Add On -https://gitlab.com/RogerChandler/ags-validator-excel-add-in