{"id":19309915,"url":"https://github.com/cedadev/nappy","last_synced_at":"2025-04-22T13:33:40.892Z","repository":{"id":25840401,"uuid":"106687389","full_name":"cedadev/nappy","owner":"cedadev","description":"NASA Ames Processing in PYthon (NAPPy) - a Python library for reading, writing and converting NASA Ames files.","archived":false,"fork":false,"pushed_at":"2025-02-03T12:01:07.000Z","size":704,"stargazers_count":9,"open_issues_count":16,"forks_count":12,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-02T00:23:20.870Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cedadev.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-12T12:04:48.000Z","updated_at":"2025-02-03T12:01:09.000Z","dependencies_parsed_at":"2024-04-10T15:33:49.603Z","dependency_job_id":"327a1dbb-d801-4131-8c69-284c6a6ea04d","html_url":"https://github.com/cedadev/nappy","commit_stats":{"total_commits":105,"total_committers":15,"mean_commits":7.0,"dds":0.4666666666666667,"last_synced_commit":"71e42a91112f52eef86183e35129b9ee2019e55b"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedadev%2Fnappy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedadev%2Fnappy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedadev%2Fnappy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedadev%2Fnappy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cedadev","download_url":"https://codeload.github.com/cedadev/nappy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250249030,"owners_count":21399379,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T00:21:37.275Z","updated_at":"2025-04-22T13:33:40.396Z","avatar_url":"https://github.com/cedadev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nappy\n\n*NASA Ames Package in Python.*\n\n## Description\n\nA NASA Ames I/O package - A python input/output package for NASA Ames file formats.\n\n## Version History\n\nThis repository was previously hosted on CEDA's Subversion repository. The first tagged release here is:\n\n - version 1.1.4\n - [all releases](https://github.com/cedadev/nappy/releases/)\n\n## Reference doc\n\nSoftware written with reference to:\n\n'Format Specification for Data Exchange' paper by Gaines and Hipkind (1998).\n`makeheader.f` fortran application to write NASA Ames headers, Anne de Rudder (2000).\nAmes python library developed by Bryan Lawrence (2003).\n\n## Conventions:\n\nThe basic NASAAmes class holds a dictionary called naVars which holds all the variables described in the Gaines and Hipkind document and these are all named using CAPITAL LETTERS for compliance/reference with that document.\n\nFor example the number of independent variables is held in the instance variable:\n\n`self[\"NIV\"]`\n\nReturn values are being calculated for many functions/methods are often prefixed with 'rt' symbolising 'return'.\n\n## Usage documentation for nappy\n\nNappy provides the following functionality:\n\n 1. A set of I/O routines for most NASA Ames File Format Indices (FFIs).\n 2. An implicit checking facility for NASA Ames compliance - i.e. if the file is formatted incorrectly then a python error will be raised. This checking facility will eventually be made explicit to report NASA Ames specific errors.\n 3. Methods to interrogate the contents the contents of NASA Ames files (such as: `naFile.getVariable()`, `naFile.getIndependentVariables()`, `naFile.getMissingValue()` etc.).\n 4. A set of  to allow conversion to and from NetCDF (for the most common FFIs) using the Xarray library. *Note* that any Xarray-compatible format can potentially be converted to NASA Ames via these libraries. In order to use this feature your software should have `nappy[netcdf_conversion]` in its requirements. \n 5. Some command line utilities for the format conversions in (4).\n\n### PYTHONPATH and import issues\n\nThe most common stumbling block for python users is getting to grips with PYTHONPATH (or `sys.path`), an environment variable used to tell python where it should look for modules and packages.  \n\nIn order for your python scripts, modules and interactive sessions to find the nappy package you must make the directory visible by pointing to it in one of the following ways.\n\nIf the nappy directory has been installed at `/my/nappy/location/nappy` then the directory you need to tell python about is `/my/nappy/location`.\n\n#### Option 1. Append your nappy path to the `PYTHONPATH` environment variable:\n\n```bash\nexport PYTHONPATH=$PYTHONPATH:/my/nappy/location\n```\n\n#### Option 2: Append your nappy path once within python:\n\n```pydoc\n\u003e\u003e\u003e import sys   # Imports the sys module\n\u003e\u003e\u003e sys.path.append(\"/my/nappy/location\")   # Adds the directory to others\n                                            # used when searching for a module.\n```\n\nYou should then be able to import nappy with:\n\n```pydoc\n\u003e\u003e\u003e import nappy\n```\n\n#### Option 3: Installing to a virtualenv\nDownload the requirements.txt file from [the nappy github page](https://github.com/cedadev/nappy) into your working directory. Then run the following commands in the terminal.\n\nOn Unix or MacOS run:\n```bash\npython -m venv .nappy-env\nsource .nappy-env/bin/activate\npip install -r requirements.txt\npip install git+https://github.com/cedadev/nappy.git\n```\n\nOn Windows PowerShell run:\n```PowerShell\npython -m venv .nappy-env\n\u0026 .nappy-env/Scripts/activate.ps1\npip install -r requirements.txt\npip install git+https://github.com/cedadev/nappy.git\n```\n\n## Usage Examples\n\nThe following examples demonstrate and overview of nappy usage:\n\n### Example 1: Opening and interrogating a NASA Ames file\n\nOpen the python interactive prompt:\n\n```bash\npython\n```\n\nImport the nappy package:\n\n```pydoc\n\u003e\u003e\u003e import nappy\n```\n\nOpen a NASA Ames file (reading the header only):\n\n```pydoc\n\u003e\u003e\u003e myfile = nappy.openNAFile('some_nasa_ames_file.na')\n```\n\nQuery the methods on the 'myfile' objects:\n\n```pydoc\n\u003e\u003e\u003e dir(myfile)\n\n['A', 'AMISS', 'ANAME', 'ASCAL', 'DATE', 'DX', 'FFI', 'IVOL', \n'LENA', 'LENX', 'MNAME', 'NAUXC', 'NAUXV', 'NCOM', 'NIV', \n'NLHEAD', 'NNCOML', 'NSCOML', 'NV', 'NVOL', 'NVPM', 'NX', \n'NXDEF', 'ONAME', 'ORG', 'RDATE', 'SCOM', 'SNAME', 'V', \n'VMISS', 'VNAME', 'VSCAL', 'X', 'XNAME', '__doc__', \n'__getitem__', '__init__', '__module__', '_checkForBlankLines', \n'_normalizeIndVars', '_normalizedX', '_open', '_parseDictionary', \n'_readAuxVariablesHeaderSection', '_readCharAuxVariablesHeaderSection',\n'_readComments', '_readCommonHeader', '_readData1', '_readData2', \n'_readLines', '_readNormalComments', '_readSpecialComments', \n'_readTopLine', '_readVariablesHeaderSection', '_setupArrays', \n'_writeAuxVariablesHeaderSection', '_writeComments', \n'_writeCommonHeader', '_writeVariablesHeaderSection', \n'auxToXarrayVariable', 'close', 'createXarrayAuxVariables', \n'createXarrayAxes', 'createXarrayVariables', 'file', 'filename', \n'floatFormat', 'getAuxMissingValue', 'getAuxScaleFactor', \n'getAuxVariable', 'getAuxVariables', 'getFFI', 'getFileDates', \n'getIndependentVariable', 'getIndependentVariables', \n'getMissingValue', 'getMission', 'getNADict', 'getNormalComments', \n'getNumHeaderLines', 'getOrg', 'getOrganisation', 'getOriginator', \n'getScaleFactor', 'getSource', 'getSpecialComments', 'getVariable', \n'getVariables', 'getVolumes', 'naDict', 'pattnBrackets', 'readData', \n'readHeader', 'delimiter', 'toXarrayAxis', 'toXarrayFile', 'toXarrayVariable', \n'writeData', 'writeHeader']\n```\n\nList the variables:\n\n```pydoc\n\u003e\u003e\u003e myfile.getVariables()\n[('Mean zonal wind', 'm/s', 200.0, 1.0)]\n```\n\nList the independent variables (or dimension axes):\n\n```pydoc\n\u003e\u003e\u003e myfile.getIndependentVariables()\n[('Altitude', 'km'), ('Latitude', 'degrees North')]\n```\n\nGet a dictionary of the file contents in the form of NASA Ames documentation:\n\n```pydoc\n\u003e\u003e\u003e myfile.getNADict()\n{'ASCAL': [1.0], 'NLHEAD': 43, 'NNCOML': 11, 'NCOM': \n['The files included in this data set illustrate each of the 9 NASA Ames file', \n'format indices (FFI). A detailed description of the NASA Ames format can be', \n'found on the Web site of the British Atmospheric Data Centre (BADC) at', \n'http://www.badc.rl.ac.uk/help/formats/NASA-Ames/', \n'E-mail contact: badc@rl.ac.uk', \n'Reference: S. E. Gaines and R. S. Hipskind, Format Specification for Data', \n'Exchange, Version 1.3, 1998. This work can be found at', \n'http://cloud1.arc.nasa.gov/solve/archiv/archive.tutorial.html', \n'and a copy of it at', \n'http://www.badc.rl.ac.uk/help/formats/NASA-Ames/G-and-H-June-1998.html', ''], \n'DX': [20.0, 10.0], 'DATE': [1969, 1, 1], 'NXDEF': [1], \n'ONAME': 'De Rudder, Anne', 'SNAME': 'Anemometer measurements averaged over longitude', \n'MNAME': 'NERC Data Grid (NDG) project', 'NX': [9], 'NSCOML': 9, \n'RDATE': [2002, 10, 31], 'AMISS': [2000.0], 'VSCAL': [1.0], 'NV': 1, \n'NVOL': 13, 'X': [[], [0.0]], 'XNAME': ['Altitude (km)', 'Latitude (degrees North)'], \n'VNAME': ['Mean zonal wind (m/s)'], 'SCOM': ['Example of FFI 2010 (b).', \n'This example illustrating NASA Ames file format index 2010 is based on results', \n'from Murgatroyd (1969) as displayed in Brasseur and Solomon, Aeronomy of the', \n'Middle Atmosphere, Reidel, 1984 (p.36). It is representative of the mean zonal', \n'wind distribution in the winter hemisphere as a function of latitude and height.', \n'The first date on line 7 (1st of January 1969) is fictitious.', \n'From line 10 (NXDEF = 1) we know that the latitude points are defined by', \n'X(i) = X(1) + (i-1)DX1 for i = 1, ..., NX', \n'with X(1) = 0 deg (line 11), DX1 = 10 deg (line 8) and NX = 9 (line 9).'], \n'VMISS': [200.0], 'IVOL': 7, 'FFI': 2010, \n'ORG': 'Rutherford Appleton Laboratory, Chilton OX11 0QX, UK - Tel.: +44 (0) 1235 445837', 'NIV': 2, \n'ANAME': ['Pressure (hPa)'], 'NAUXV': 1}\n```\n\nGrab the normal comments:\n\n```pydoc\n\u003e\u003e\u003e comm=myfile.na_dict[\"NCOM\"]\n\u003e\u003e\u003e print(comm)\n['The files included in this data set illustrate each of the 9 NASA Ames file', \n'format indices (FFI). A detailed description of the NASA Ames format can be', \n'found on the Web site of the British Atmospheric Data Centre (BADC) at', \n'http://www.badc.rl.ac.uk/help/formats/NASA-Ames/', 'E-mail contact: badc@rl.ac.uk', \n'Reference: S. E. Gaines and R. S. Hipskind, Format Specification for Data', \n'Exchange, Version 1.3, 1998. This work can be found at', \n'http://cloud1.arc.nasa.gov/solve/archiv/archive.tutorial.html', \n'and a copy of it at', \n'http://www.badc.rl.ac.uk/help/formats/NASA-Ames/G-and-H-June-1998.html', '']\n```\n\nUse the file method to get the normal comments:\n\n```pydoc\n\u003e\u003e\u003e myfile.getNormalComments()\n['The files included in this data set illustrate each of the 9 NASA Ames file', \n'format indices (FFI). A detailed description of the NASA Ames format can be', \n'found on the Web site of the British Atmospheric Data Centre (BADC) at', \n'http://www.badc.rl.ac.uk/help/formats/NASA-Ames/', 'E-mail contact: badc@rl.ac.uk',\n'Reference: S. E. Gaines and R. S. Hipskind, Format Specification for Data', \n'Exchange, Version 1.3, 1998. This work can be found at', \n'http://cloud1.arc.nasa.gov/solve/archiv/archive.tutorial.html', \n'and a copy of it at', \n'http://www.badc.rl.ac.uk/help/formats/NASA-Ames/G-and-H-June-1998.html', '']\n```\n\nRead the actual data:\n\n```pydoc\n\u003e\u003e\u003e myfile.readData()\n```\n\nInspect the data array (\"V\") in the NASA Ames dictionary:\n\n```pydoc\n\u003e\u003e\u003e print(myfile.na_dict[\"V\"])\n[[[-3.0, -2.6000000000000001, -2.2999999999999998, 2.0, 4.7999999999999998, \n4.5999999999999996, 4.5, 3.0, -0.90000000000000002], [-15.1, -4.2000000000000002, \n6.9000000000000004, 12.800000000000001, 14.699999999999999, 20.0, 21.5, 18.0, \n8.1999999999999993], [-29.0, -15.199999999999999, 3.3999999999999999, \n28.199999999999999, 41.0, 39.100000000000001, 17.899999999999999, 8.0, \n0.10000000000000001], [-10.0, 8.4000000000000004, 31.199999999999999, \n59.899999999999999, 78.5, 77.700000000000003, 47.0, 17.600000000000001, \n16.0], [200.0, 200.0, 200.0, 200.0, 200.0, 200.0, 200.0, 200.0, 200.0]]]\n```\n\n### Example 2: Writing a NASA Ames file\n\nStart the python interactive prompt:\n\n```pydoc\npython\n```\n\nImport the nappy package:\n\n```pydoc\n\u003e\u003e\u003e import nappy\n```\n\nPretend you have created a complete NASA Ames file contents in a dictionary called `na_contents`.\n\nWrite the data to a NASA Ames file:\n\n```pydoc\n\u003e\u003e\u003e nappy.openNAFile('my_file_to_write.na', 'w', na_contents)\n```\n\n### Example 3: Converting a NASA Ames file to a NetCDF file\n\n*[Note: this utility is only available on Unix/linux platforms]*\n\nRun the command-line utility `na2nc`:\n\n```bash\nna2nc -t \"seconds since 1999-01-01 00:00:00\" -i my_nasa_ames_file.na -o my_netcdf_file.nc\n```\n\nNote that the `-t` argument allows you to pass a NetCDF-style data/time units description into your NetCDF that will allow software packages to identify the time axis correctly. This is required when the time unit string in your NASA Ames file is non-standard.\n\nFor help on the command-line utility type:\n\n```bash\nna2nc -h\n\nna2nc.py\n========\n\nConverts a NASA Ames file to a NetCDF file.\n\nUsage\n=====\n\n   na2nc.py [-m \u003cmode\u003e] [-g \u003cglobal_atts_list\u003e]\n            [-r \u003crename_vars_list\u003e] [-t \u003ctime_units\u003e] [-n]\n            -i \u003cna_file\u003e [-o \u003cnc_file\u003e]\n\nWhere\n-----\n\n    \u003cmode\u003e                      is the file mode, either \"w\" for write or \"a\" for append\n    \u003cglobal_atts_list\u003e          is a comma-separated list of global attributes to add\n    \u003crename_vars_list\u003e          is a comma-separated list of \u003cold_name\u003e,\u003cnew_name\u003e pairs to rename variables\n    \u003ctime_units\u003e                is a valid time units string such as \"hours since 2003-04-30 10:00:00\"\n    -n                          suppresses the time units warning if invalid\n    \u003cna_file\u003e                   is the input NASA Ames file path\n    \u003cnc_file\u003e                   is the output NetCDF file path (default is to replace \".na\" from NASA Ames\n                                 file with \".nc\").\n```\n\n### Example 4: Converting a NetCDF file to a NASA Ames file\n\n*[Note: this utility is only available on Unix/linux platforms]*\n\nRun the command-line utility `nc2na`:\n\n```bash\nnc2na -i my_netcdf_file.nc -o my_nasa_ames_file.na\n```\n\nFor help on the command-line utility type:\n\n```bash\nnc2na -h\n\nnc2na.py\n========\n\nConverts a NetCDF file into one or more NASA Ames file.\n\nUsage\n=====\n\n    nc2na.py [-v \u003cvar_list\u003e] [--ffi=\u003cffi\u003e] [-f \u003cfloat_format\u003e]\n             [-d \u003cdelimiter\u003e] [-l \u003climit_ffi_1001_rows\u003e]\n             [-e \u003cexclude_vars\u003e] [--overwrite-metadata=\u003ckey1\u003e,\u003cvalue1\u003e[,\u003ckey2\u003e,\u003cvalue2\u003e[...]]]\n             [--names-only] [--no-header] [--annotated]\n             -i \u003cnc_file\u003e [-o \u003cna_file\u003e]\nWhere\n-----\n\n    \u003cnc_file\u003e                   - name of input file (NetCDF).\n    \u003cna_file\u003e                   - name of output file (NASA Ames or CSV) - will be used as base name if multiple files.\n    \u003cvar_list\u003e                  - a comma-separated list of variables (i.e. var ids) to include in the output file(s).\n    \u003cffi\u003e                       - NASA Ames File Format Index (FFI) to write to (normally automatic).\n    \u003cfloat_format\u003e              - a python formatting string such as %s, %g or %5.2f\n    \u003cdelimiter\u003e                 - the delimiter you wish to use between data items in the output file such as \"   \" or \"    \"\n    \u003climit_ffi_1001_rows\u003e       - if format FFI is 1001 then chop files up into \u003climitFFI1001Rows\u003e rows of data.\n    \u003cexclude_vars\u003e              - a comma-separated list of variables (i.e. var ids) to exclude in the output file(s).\n    \u003ckey1\u003e,\u003cvalue1\u003e[,\u003ckey2\u003e,\u003cvalue2\u003e[...]] - list of comma-separated key,value pairs to overwrite in output files:\n                                                                * Typically the keys are in:\n                                   * \"DATE\", \"RDATE\", \"ANAME\", \"MNAME\",\"ONAME\", \"ORG\", \"SNAME\", \"VNAME\".\n    --names-only                - only display a list of file names that would be written (i.e. don't convert actual files).\n    --no-header                 - Do not write NASA Ames header\n    --annotated                 - add annotation column in first column\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcedadev%2Fnappy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcedadev%2Fnappy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcedadev%2Fnappy/lists"}