Metadata-Version: 2.4
Name: dshipparser
Version: 0.3.3
Summary: parsing dship exports into pandas dataframe
Home-page: https://git.geomar.de/dm/dship_parser
Author: Claas Faber
Author-email: cfaber@geomar.de
License: Copyright (c) 2018, Claas Faber, GEOMAR Data Management
        
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without modification, are NOT PERMITTED
        without prior permission by GEOMAR data management team. INTERNAL USE ONLY.
        
        Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
        Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Requires-Python: >3.10
License-File: LICENSE
Requires-Dist: click
Requires-Dist: pandas
Requires-Dist: xmltodict
Requires-Dist: chardet
Requires-Dist: python-dateutil
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# A parser for DSHIP-exports

## DSHIP system on German research vessels
This is a python package capable of parsing exports of DSHIP data.
DSHIP is running on most large German research vessels and
records data from the ships nautical, metereological and scientific
sensors into a central database. This data can be exported by one
of three DSHIP land systems:

- AWI (http://dship.bsh.de):
    - RV Polarstern
    - RV Heincke
    - RV Mya

- BSH (https://dship.awi.de):
    - RV Sonne
    - RV Maria S Merian
    - RV Meteor

- GEOMAR (http://dship.geomar.de):
    - RV Alkor
    - RV Poseidon

Follow links above for detailed instructions on how to extract date.
You might be asked for credentials for accessing the land systems, which
can be provided on request to datamanagement@geomar.de

## DSHIP export format and `dshipparser`
Exports from dship come as a compressed file, containing three files: one data file,
one xml file with export settings and metadata and one text file with logs from the exporter.
The exact nature of these files varies between different versions of DSHIP.

When creating the exports, you can choose various settings, e.g. parameters to export,
time period and resolution, NaN values etc.

The `dshipparser` understands exports of all versions. It will honor the
configured NaN values and will parse timestamps and latitude/longitude information
into standardised formats. The exported data will be available as a pandas dataframe
for further processing.

## Installation
### Using `pip`:
TODO: change URL
```bash
bash$ pip install --extra-index-url https://pypi.fury.io/cfgmr/ dshipparser
```

### From Source code
TODO: change URL
Clone this repo and install using pip
```bash
bash$ mkdir base
bash$ cd base
bash$ git clone git@git.geomar.de:dm/dship_parser.git
bash$ pip install -e ./dship_parser/
```


## Usage
```python
from dshipparser import parser
df = parser.parse_data('/path/to/extracted/dship/export')
```
`df` will have ISO-formated timestamp as index and each of the selected
parameters as columns. If known lat/lon parameters were selected, the
`df` will have the columns `_POS_LAT_` and `_POS_LON_` with latitude and
longitude information in decimal degrees.

You can also explore the metadata information:
```python
from dshipparser.parser import DshipParser
dsp = DshipParser('/Users/cfaber/misc/dship_parser/tests/test_data/dship3_export/dship_format_update')
dsp.export_info.export_info
Out[10]:
{'platform_id': 'MSM',
 'dat_file': '/Users/cfaber/misc/dship_parser/tests/test_data/dship3_export/dship_format_update/underway-export-merian.dat',
 'file_format': OrderedDict([('@datetimeformat', 'YYYYMMDDTHHmmss'),
              ('@decimalsymbol', '.'),
              ('@endofrecordmarker', '\\n'),
              ('@fillvalue', 'false'),
              ('@headerrow', 'false'),
              ('@separator', '\\t')]),
 'columns': ['SYS.STR.Course',
  'SYS.STR.DPT',
  [...]
```


## Contribute

If you find a bug or if you would like to actively work on `dshipparser`, please
send a mail to datamanagement@geomar.de