mutts 1.0.0__py3-none-any.whl → 1.0.3__py3-none-any.whl

mutts/cli.py

@@ -43,7 +43,11 @@ def format_worksheet(worksheet):
 @click.command()
 @click.option("--submission", "-s", required=True, help="Metadata submission id.")
 @click.option(
-    "--user-facility", "-u", required=True, help="User facility to send data to."
+    "--user-facility",
+    "-u",
+    required=True,
+    type=click.Choice(list(MetadataRetriever.USER_FACILITY_DICT.keys()), case_sensitive=False),
+    help="User facility to send data to."
 )
 @click.option("--header/--no-header", "-h", default=False, show_default=True)
 @click.option(
@@ -103,22 +107,26 @@ def cli(
         # Write the generated data to 'DATA SHEET'
         user_facility_spreadsheet.to_excel(writer, index=False, sheet_name='DATA SHEET')
 
-        # Path to static JGI v15 Excel template
-        static_excel_path = os.path.join(
-            os.path.dirname(__file__), '..', '..',
-            'input-files', 'static-excel-tabs', 'JGI.Metagenome.NA.v15.xlsx'
-        )
-
-        # Copy INSTRUCTIONS and PLATE LOCATIONS sheets from JGI v15 template
-        # static file if it exists
-        if os.path.exists(static_excel_path):
-            static_excel = pd.ExcelFile(static_excel_path)
-            if 'INSTRUCTIONS' in static_excel.sheet_names:
-                instructions_df = pd.read_excel(static_excel, 'INSTRUCTIONS')
-                instructions_df.to_excel(writer, index=False, sheet_name='INSTRUCTIONS')
-            if 'PLATE LOCATIONS' in static_excel.sheet_names:
-                plate_locations_df = pd.read_excel(static_excel, 'PLATE LOCATIONS')
-                plate_locations_df.to_excel(writer, index=False, sheet_name='PLATE LOCATIONS')
+        # Check if mapper is one of the v15 JGI templates
+        mapper_basename = os.path.basename(mapper)
+        jgi_v15_mappers = ['jgi_mg_header_v15.json', 'jgi_mt_header_v15.json']
+
+        if mapper_basename in jgi_v15_mappers:
+            # Path to static JGI v15 Excel template
+            static_excel_path = os.path.join(
+                os.path.dirname(__file__), 'static-excel-tabs', 'JGI.Metagenome.NA.v15.xlsx'
+            )
+
+            # Copy INSTRUCTIONS and PLATE LOCATIONS sheets from JGI v15 template
+            # static file if it exists
+            if os.path.exists(static_excel_path):
+                static_excel = pd.ExcelFile(static_excel_path)
+                if 'INSTRUCTIONS' in static_excel.sheet_names:
+                    instructions_df = pd.read_excel(static_excel, 'INSTRUCTIONS')
+                    instructions_df.to_excel(writer, index=False, sheet_name='INSTRUCTIONS')
+                if 'PLATE LOCATIONS' in static_excel.sheet_names:
+                    plate_locations_df = pd.read_excel(static_excel, 'PLATE LOCATIONS')
+                    plate_locations_df.to_excel(writer, index=False, sheet_name='PLATE LOCATIONS')
 
         # Apply formatting to all sheets
         for sheet_name in writer.book.sheetnames:

mutts/spreadsheet.py

@@ -7,6 +7,9 @@ class SpreadsheetCreator:
     Creates a spreadsheet based on a JSON mapper and metadata DataFrame.
     """
 
+    # List of JGI-specific user facilities
+    JGI_FACILITIES = ['jgi_mg', 'jgi_mt', 'jgi_mg_lr']
+
     def __init__(
         self,
         user_facility: str,
@@ -16,6 +19,7 @@ class SpreadsheetCreator:
         """
         Initialize the SpreadsheetCreator.
 
+        :param user_facility: The user facility identifier.
         :param json_mapper: The JSON mapper specifying column mappings.
         :param metadata_df: The metadata DataFrame to create the spreadsheet from.
         """
@@ -66,10 +70,20 @@ class SpreadsheetCreator:
                 "sub_port_mapping" in v
                 and v["sub_port_mapping"] in self.metadata_df.columns.to_list()
             ):
+                # Get the column data
+                column_data = self.metadata_df[v["sub_port_mapping"]]
+
+                # For JGI facilities, remove "_data" suffix from `sample_isolated_from` values
+                if (
+                    self.user_facility in self.JGI_FACILITIES
+                    and v["sub_port_mapping"] == "sample_isolated_from"
+                ):
+                    column_data = column_data.str.replace("_data", "", regex=False)
+
                 if "header" in v:
-                    rows_df[v["header"]] = self.metadata_df[v["sub_port_mapping"]]
+                    rows_df[v["header"]] = column_data
                 else:
-                    rows_df[k] = self.metadata_df[v["sub_port_mapping"]]
+                    rows_df[k] = column_data
 
         return rows_df
 

mutts-1.0.3.dist-info/METADATA

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: mutts
+Version: 1.0.3
+Summary: Metadata for User facility Template Transformations
+License: MIT
+Keywords: NMDC,US DOE user facilities,metadata translation
+Author: Sujay Patil
+Author-email: spatil@lbl.gov
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: click (>=8.1.7,<9.0.0)
+Requires-Dist: openpyxl (>=3.1.0,<4.0.0)
+Requires-Dist: pandas (>=2.2.0,<3.0.0)
+Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
+Requires-Dist: requests (>=2.32.0,<3.0.0)
+Project-URL: Homepage, https://github.com/microbiomedata/metadata-for-user-facility-template-transformations
+Project-URL: Repository, https://github.com/microbiomedata/metadata-for-user-facility-template-transformations
+Description-Content-Type: text/markdown
+
+# Metadata for User facility Template Transformations (MUTTs)
+
+## Table of Contents
+- [Metadata for User facility Template Transformations (MUTTs)](#metadata-for-user-facility-template-transformations-mutts)
+  - [Table of Contents](#table-of-contents)
+  - [Introduction](#introduction)
+  - [MUTTs User Documentation](#mutts-user-documentation)
+    - [Prerequisites](#prerequisites)
+    - [Installation](#installation)
+    - [Usage](#usage)
+      - [Example 1: Generate a JGI Metagenome spreadsheet](#example-1-generate-a-jgi-metagenome-spreadsheet)
+      - [Example 2: Generate a JGI Metagenome v15 spreadsheet](#example-2-generate-a-jgi-metagenome-v15-spreadsheet)
+      - [Example 3: Generate an EMSL spreadsheet](#example-3-generate-an-emsl-spreadsheet)
+      - [Command Options](#command-options)
+  - [MUTTs Developer Documentation](#mutts-developer-documentation)
+    - [Software Requirements](#software-requirements)
+    - [Development Installation](#development-installation)
+    - [Creating Custom Mapper Files](#creating-custom-mapper-files)
+
+## Introduction
+
+The programs bundled in this repository automatically retrieve Biosample metadata records for studies submitted to NMDC through the [NMDC Submission Portal](https://data.microbiomedata.org/submission/home), and convert the metadata into Excel spreadsheets that are accepted by [DOE user facilities](https://www.energy.gov/science/office-science-user-facilities).
+
+---
+
+## MUTTs User Documentation
+
+The documentation and setup instructions in this section are meant for any user who would like to install the MUTTs Python package and use it's transformation capabilities to convert data from the NMDC Submission Portal into an Excel spreadsheet that follows a template, based on the MUTTs JSON mapper file that is used.
+
+### Prerequisites
+- [Python](https://www.python.org/downloads/) 3.12 or higher
+- An [NMDC user account](https://data.microbiomedata.org/) with an API access token
+
+> To create an NMDC user account you will need to sign up at the above link by clicking on the 'ORCID LOGIN' button/link at the top right corner of the NMDC site, and signing in appropriately with your ORCID credentials
+
+**Setting up your API access token**
+
+This is required for running the examples in the [Usage](#usage) section below (after going through all the [Installation](#installation) steps).
+
+Create a `.env` file in your working directory:
+```bash
+echo "DATA_PORTAL_REFRESH_TOKEN=your_token_here" > .env
+```
+
+To get your access token:
+1. Visit https://data.microbiomedata.org/user
+2. Copy your Refresh Token
+3. Replace `your_token_here` in the `.env` file with your token
+
+### Installation
+
+1. **Create a virtual environment** (recommended)
+```bash
+python -m venv mutts-env
+source mutts-env/bin/activate  # On Windows: mutts-env\Scripts\activate
+```
+
+2. **Install the MUTTs package from PyPI**
+```bash
+pip install mutts
+```
+
+3. **Download any of the MUTTs JSON mapper configuration files**
+
+*Note*: It is not mandatory that you need to download/use any of the pre-existing/already defined JSON mapper files that are present in this repository. You can always define your own custom JSON mapper files that follow a format similar to the ones defined in this repo.
+
+Create a directory for your mapper files and download them from this repository:
+```bash
+mkdir input-files
+cd input-files
+```
+
+Download the mapper files you need from the [input-files directory](https://github.com/microbiomedata/metadata-for-user-facility-template-transformations/tree/main/input-files):
+- For EMSL: `emsl_header.json`
+- For JGI Metagenome: `jgi_mg_header.json` or `jgi_mg_header_v15.json`
+- For JGI Metatranscriptome: `jgi_mt_header.json` or `jgi_mt_header_v15.json`
+
+### Usage
+
+Run the `mutts` command with the required options:
+
+```bash
+mutts --help
+```
+
+Note: In the below examples there is a `--submission` optional argument that requires you to pass it an NMDC Submission UUID as value, and the way you would get that is from the URL of the Submission page when you open it up from the Submission Portal.
+
+An example would look like below:
+
+```
+https://data.microbiomedata.org/submission/<submission-uuid>/samples
+```
+
+#### Example 1: Generate a JGI Metagenome spreadsheet
+```bash
+mutts --submission <submission-uuid> \
+      --unique-field samp_name \
+      --user-facility jgi_mg \
+      --mapper input-files/jgi_mg_header.json \
+      --output my-samples_jgi.xlsx
+```
+
+#### Example 2: Generate a JGI Metagenome v15 spreadsheet
+```bash
+mutts --submission <submission-uuid> \
+      --unique-field samp_name \
+      --user-facility jgi_mg \
+      --mapper input-files/jgi_mg_header_v15.json \
+      --output my-samples_jgi_v15.xlsx
+```
+
+#### Example 3: Generate an EMSL spreadsheet
+```bash
+mutts --submission <submission-uuid> \
+      --user-facility emsl \
+      --mapper input-files/emsl_header.json \
+      --header \
+      --unique-field samp_name \
+      --output my-samples_emsl.xlsx
+```
+
+#### Command Options
+
+- `-s, --submission`: Your NMDC metadata submission UUID (required)
+- `-u, --user-facility`: Target facility (required): `emsl`, `jgi_mg`, `jgi_mg_lr`, or `jgi_mt`
+- `-m, --mapper`: Path to the JSON mapper file (required)
+- `-uf, --unique-field`: Field to uniquely identify records (required, typically `samp_name`)
+- `-o, --output`: Output Excel file path (required)
+- `-h, --header`: Include headers in output (use for EMSL, omit for JGI)
+
+---
+
+## MUTTs Developer Documentation
+
+The documentation and setup instructions in this section are largely meant for any developer/programmer whose primary use case is to extend/improve/build upon the current capabilities of the MUTTs software.
+
+The software consists of two main components:
+
+1. **JSON Mapper Configuration Files**
+- Controls/specifies the mapping between columns from the NMDC Submission Portal and column names used in the output spreadsheets
+- Top-level keys indicate main headers in the output
+- Numbered keys add clarifying header information
+- The `header` keyword allows custom column names
+- The `sub_port_mapping` keyword specifies mappings between Submission Portal columns/slots (as dictated by the [NMDC submission schema](https://microbiomedata.github.io/submission-schema/)) and user facility template columns
+- Examples available in [input-files/](input-files/)
+
+1. **`mutts` CLI**
+- Command-line application that performs the metadata conversion
+- Consumes mapper files and submission data as inputs
+
+### Software Requirements
+- [Poetry](https://python-poetry.org/docs/#installing-with-the-official-installer)
+- [Python](https://www.python.org/downloads/release/python-390/) 3.12 or higher
+
+### Development Installation
+
+1. Clone this repository
+```bash
+git clone https://github.com/microbiomedata/metadata-for-user-facility-template-transformations.git
+cd metadata-for-user-facility-template-transformations
+```
+
+2. Install dependencies with Poetry
+```bash
+poetry install
+```
+
+This installs the `mutts` package in development mode and creates the `mutts` command-line tool.
+
+3. Set up your `.env` file
+```bash
+cp .env.example .env  # if available, or create a new .env file
+```
+
+Add your NMDC API token:
+```
+DATA_PORTAL_REFRESH_TOKEN=your_token_here
+```
+
+Get your token from: https://data.microbiomedata.org/user
+
+4. Run the CLI in development mode
+```bash
+poetry run mutts --help
+```
+
+### Creating Custom Mapper Files
+
+To create a custom mapper for a new user facility, refer to the existing examples:
+- [emsl_header.json](input-files/emsl_header.json) - EMSL configuration
+- [jgi_mg_header.json](input-files/jgi_mg_header.json) - JGI Metagenome configuration
+- [jgi_mt_header.json](input-files/jgi_mt_header.json) - JGI Metatranscriptome configuration
+- [jgi_mg_header_v15.json](input-files/jgi_mg_header_v15.json) - JGI Metagenome v15 configuration
+- [jgi_mt_header_v15.json](input-files/jgi_mt_header_v15.json) - JGI Metatranscriptome v15 configuration
+

mutts-1.0.3.dist-info/RECORD

@@ -0,0 +1,9 @@
+mutts/__init__.py,sha256=iTcKOq5Id9qudNWyTGPJyJGuS19yG-FhPlmSfuJM7jU,217
+mutts/cli.py,sha256=YzRnMLEtbFc2yuAYqWoljvk0Z9IEHDw3XefjTZE8Rbg,4912
+mutts/retriever.py,sha256=B9cShEaeOY4BN1nWaML_UzMTR971X4rn1XfqyvZhAno,8333
+mutts/spreadsheet.py,sha256=hSEEkTcTmkEFsktGG1_s4gAPuDys9Dnzbdk9cfJKwcY,5053
+mutts/static-excel-tabs/JGI.Metagenome.NA.v15.xlsx,sha256=tYlYX5QZVjiiCrsCsxfL73O0BdvlqttBjUyqXsv8s7s,22099
+mutts-1.0.3.dist-info/METADATA,sha256=JU9879qBfZ0iLTHWHCR1J6XUyUSXPq1sSOm7wW0b0Zg,8928
+mutts-1.0.3.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+mutts-1.0.3.dist-info/entry_points.txt,sha256=rDp08H4MnNWGYHFE6ZAqOocRyTp68IPJsjXTcQppi8s,39
+mutts-1.0.3.dist-info/RECORD,,

{mutts-1.0.0.dist-info → mutts-1.0.3.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.1.3
+Generator: poetry-core 2.2.1
 Root-Is-Purelib: true
 Tag: py3-none-any

mutts-1.0.0.dist-info/METADATA

@@ -1,18 +0,0 @@
-Metadata-Version: 2.3
-Name: mutts
-Version: 1.0.0
-Summary: Metadata for User facility Template Transformations
-Author: Sujay Patil
-Author-email: spatil@lbl.gov
-Requires-Python: >=3.9,<4.0
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: click (>=8.1.3,<9.0.0)
-Requires-Dist: openpyxl (>=3.0.10,<4.0.0)
-Requires-Dist: pandas (>=1.5.2,<2.0.0)
-Requires-Dist: python-dotenv (>=0.21.1,<0.22.0)
-Requires-Dist: requests (>=2.28.2,<3.0.0)

mutts-1.0.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-mutts/__init__.py,sha256=iTcKOq5Id9qudNWyTGPJyJGuS19yG-FhPlmSfuJM7jU,217
-mutts/cli.py,sha256=Zqhv9Yeu7LOtRh38izhekSATb0yveqjLGH-qO9tc9Jk,4551
-mutts/retriever.py,sha256=B9cShEaeOY4BN1nWaML_UzMTR971X4rn1XfqyvZhAno,8333
-mutts/spreadsheet.py,sha256=5iTWcBBWm06avW5Xt7YvcgqbuOkgEmPJKqd2xcb63M8,4487
-mutts-1.0.0.dist-info/METADATA,sha256=w4iXydlpLKo16Fefj1E7GdBGbbL1Mc_X8NZqO07NQtY,698
-mutts-1.0.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-mutts-1.0.0.dist-info/entry_points.txt,sha256=rDp08H4MnNWGYHFE6ZAqOocRyTp68IPJsjXTcQppi8s,39
-mutts-1.0.0.dist-info/RECORD,,