Merge branch 'develop' into 'main'

stages:

  - test

  - deploy_html_docs

.test:

  image: python:$PYTHON_VERSION

  stage: test

  parallel:

    matrix:

      - PYTHON_VERSION: ["3.7", "3.8", "3.9", "3.10"]

      - PYTHON_VERSION: ["3.8", "3.9", "3.10", "3.11", "3.12"]

  script:

    - python -m pip install .

    - python -m pip install pytest nbval

    - python -m pytest -v --ignore=tests/test_batch.py

    - python -m doctest README.md

    - python -m pip install striplog

    - python -m pytest -v --nbval examples/Plot_locations_and_create_strip_log.ipynb

    - python -m pytest -v --nbval notebooks/Plot_locations_and_create_strip_log.ipynb

build-linux:

  extends: .test

  tags:

    - linux

pages:

  stage: deploy_html_docs

  image: python:3.10

  script:

  - pip install -U sphinx sphinx-rtd-theme

  - cd docs

  - sphinx-build -b html . ../public

  - cp custom.css ../public/_static/custom.css # Custom CSS file to increase width of html pages

  artifacts:

    paths:

    - public

  rules:

    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

![PyPI](https://img.shields.io/pypi/v/python-ags4?label=Current%20Release)

![PyPI - Downloads](https://img.shields.io/pypi/dm/python-ags4?label=Downloads%20pypi)

![Conda](https://img.shields.io/conda/dn/conda-forge/python-ags4?label=Downloads%20conda-forge)

[![DOI](https://joss.theoj.org/papers/10.21105/joss.04569/status.svg)](https://doi.org/10.21105/joss.04569)

![Tests](https://gitlab.com/ags-data-format-wg/ags-python-library/badges/main/pipeline.svg?ignore_skipped=true&key_text=Tests)

# python-ags4

[[_TOC_]]

## Documentation

### Juypter Notebook

We have created an example Juypter Notebook which imports an AGS file, plots boreholes on a map and creates a Striplog.  

[See here](./examples/Plot_locations_and_create_strip_log.ipynb)

### Installation

```bash

>>>

**Note**

Installation requires Python 3.7 or later.

Installation requires Python 3.8 or later.

>>>

### Code Examples

from python_ags4 import AGS4

```

#### Import data from an AGS4 file:

#### Import data from an AGS4 file

```python

# Load from a file

The `AGS4.convert_to_numeric()` function automatically converts all columns in the input DataFrame with the a numeric *TYPE* to a float. (*Note: The UNIT and TYPE rows are removed during this operation as they are non-numeric.*)

#### Export data back to an AGS4 file:

#### Export data back to an AGS4 file

``` python

AGS4.dataframe_to_AGS4(tables, headings, 'output.ags')

Tables converted to numeric using the ```AGS4.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 Notebook

We have created an example Juypter Notebook which imports an AGS file, plots boreholes on a map and creates a Striplog.  

[See here](./notebooks/Plot_locations_and_create_strip_log.ipynb)

### Command Line Interface 

A 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 running ```python pip install python-ags4>=0.2.0```

Please refer to the [Wiki](https://gitlab.com/ags-data-format-wg/ags-python-library/-/wikis/home) page for details about the development environment and how to get involved in the project.

API documentation available at https://ags-data-format-wg.gitlab.io/ags-python-library

### Citation

Senanayake 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.04569

## Implementations

This library has been used to create

Changelog

=========

0.5.0 (2024-01-27)

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

- Remove support for Python version 3.7

- Add support for Pandas version 2.x and drop support for version 1.x.

- Add functionality to log internal messages

- Add functionality for FYI and warning messages

- Return error message if multiple instances of the same group are found.

  Previous behavior was to simply overwrite the data.

- Update check for Rule 1 to allow extend ASCII characters

- Improve checks for data types DMS, DT, and SF under Rule 8

- Improve check for Rule 10b and avoid returning duplicate error messages

- Improve check for Rule 15 to include units defined in PU columns

- Improve check for Rule 16 to provide warning if a user-defined abbreviation

  duplicates an existing standard abbreviation for the same field

- Update check_file() to handle an already opened file or stream. The first

  parameter name input_file is changed to filepath_or_buffer.

- Reinstate deprecated fields/groups that had been deleted from the v4.1.1

  standard dictionary

- Add summary of data to error log

0.4.1 (2022-09-12)

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

# Minimal makefile for Sphinx documentation

#

# You can set these variables from the command line, and also

# from the environment for the first two.

SPHINXOPTS    ?=

SPHINXBUILD   ?= sphinx-build

SOURCEDIR     = .

BUILDDIR      = _build

# Put it first so that "make" without argument is like "make help".

help:

	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new

# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

%: Makefile

	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

# Configuration file for the Sphinx documentation builder.

#

# For the full list of built-in configuration values, see the documentation:

# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------

# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

#

import os

import sys

sys.path.insert(0, os.path.abspath('..'))

import python_ags4

project = 'python_ags4'

copyright = '2020-2023 Asitha Senanayake'

author = 'Asitha Senanayake'

release = python_ags4.__version__

# -- General configuration ---------------------------------------------------

# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.viewcode','sphinxcontrib.jquery']

# Autodoc settings

autodoc_member_order = 'alphabetical'

add_module_names = False

# Napoleon settings

napoleon_google_docstring = True

napoleon_numpy_docstring = True

napoleon_include_init_with_doc = False

napoleon_include_private_with_doc = False

napoleon_include_special_with_doc = True

napoleon_use_admonition_for_examples = False

napoleon_use_admonition_for_notes = False

napoleon_use_admonition_for_references = False

napoleon_use_ivar = False

napoleon_use_param = True

napoleon_use_rtype = True

napoleon_preprocess_types = False

napoleon_type_aliases = None

napoleon_attr_annotations = True

templates_path = ['_templates']

exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'joss_paper/paper.md']

source_suffix = {'.rst': 'restructuredtext',

                 '.md': 'markdown'}

# -- Options for HTML output -------------------------------------------------

# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme_options = {

    'logo_only': False,

    'display_version': True,

    'prev_next_buttons_location': 'bottom',

    'style_external_links': False,

    'vcs_pageview_mode': '',

    'style_nav_header_background': 'white',

    # Toc options

    'collapse_navigation': False,

    'sticky_navigation': True,

    'navigation_depth': 4,

    'includehidden': True,

    'titles_only': False

}

# html_theme = 'alabaster'

html_theme = 'sphinx_rtd_theme'

html_static_path = ['_static']

html_css_files = ['custom.css']