X-ray Atlas

https://github.com/wsu-carbon-lab/xray-atlas
Admin
X-ray Atlas is an open database and web application for sharing, exploring, and analyzing Near-Edge...
Tokens:27,963
Snippets:265
Trust Score:6.8
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Prerequisites with Homebrew

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Installs Bun, ngrok, and Infisical CLI on macOS using Homebrew. Verifies installations.

```bash
# macOS (using Homebrew)
brew install oven-sh/bun/bun
brew install ngrok
brew install infisical/get-cli/infisical

# Verify installations
bun --version
ngrok --version
infisical --version
```

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

### Start Standard Development Server

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Run this command for standard local development on localhost. This starts the Next.js development server.

```bash
bun dev
```

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

### Graphite CLI Installation and Usage

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Install the Graphite CLI using Homebrew and use its commands for branch management and PR submission.

```bash
# Install Graphite CLI
brew install withgraphite/tap/graphite
```

```bash
# Create a new branch
gt create feat/new-feature
```

```bash
# Stack another branch on top
gt create feat/dependent-feature
```

```bash
# Restack all branches on main
gt restack
```

```bash
# Submit PRs for the stack
gt submit --stack
```

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

### Start Development with ngrok Tunnel

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Run this command to start both the Next.js development server and an ngrok tunnel concurrently. This is essential for local OAuth testing as it provides a public HTTPS URL.

```bash
bun dev:tunnel
```

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

### Conventional Commit Message Examples

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification. Use these to structure your commit messages for clarity and automation.

```bash
feat(molecules): add SMILES structure search
```

```bash
fix(auth): resolve ORCID callback cookie issue
```

```bash
docs(contributing): add ngrok setup guide
```

```bash
refactor(plots): extract axis components
```

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

### GET /api/physics/atomic-form-factor

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Proxies Henke/LBL `.nff` data for a single element's atomic form factor (scattering factor).

```APIDOC
## GET /api/physics/atomic-form-factor

### Description
Proxies Henke/LBL `.nff` data for a single element symbol. Used internally by the bare-atom normalization pipeline.

### Method
GET

### Endpoint
`/api/physics/atomic-form-factor`

### Parameters
#### Query Parameters
- **atom** (string) - Required - The chemical symbol of the element (e.g., 'C', 'N').

### Response
- **data** (string) - A string containing energy (eV), f1, and f2 values, space-separated.

### Error Response
- **400 Bad Request** - If the atom symbol is invalid.
  - **error** (string) - Description of the error.
```

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

### Get Atomic Form Factor Data

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Proxies CXRO scattering factor data for a single element. Used for bare-atom normalization. Supports GET requests with an 'atom' query parameter.

```bash
curl "https://xrayatlas.org/api/physics/atomic-form-factor?atom=C"
# Returns: { "data": "E(eV)  f1  f2\n10.00  -9.512  0.0787\n..." }

curl "https://xrayatlas.org/api/physics/atomic-form-factor?atom=N"
# Error: { "error": "Invalid atom symbol" }   (if not matching /^[A-Z][a-z]?$/)
```

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

### Manually Create .env.local File

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Copies the template .env.example file to .env.local for manual environment variable configuration. This is an alternative if Infisical is not used.

```bash
# Copy the template
cp .env.example .env.local
```

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

### Generate Prisma Client

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Run this command after modifying the Prisma schema to generate the Prisma client. Ensure `bun run postinstall` is executed.

```bash
bun run postinstall
```

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

### Explore Data with Prisma Studio

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Launch Prisma Studio to visually explore and manage your database content. This command opens the Prisma Studio GUI.

```bash
bun run db:studio
```

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

### Infisical CLI Login and Initialization

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Logs into the Infisical CLI and initializes the project for secrets management. Selects the 'xray-atlas' project and 'development' environment.

```bash
infisical login
cd xray-atlas
infisical init
```

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

### GET /api/molecules/search

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Resolves a search term to a molecule detail page via a 307 redirect if a confident match is found, or redirects to the browse page.

```APIDOC
## GET /api/molecules/search

### Description
Resolves a search term to a molecule detail page (307 redirect) when there is a confident best match, or redirects to the browse page with `?q=` preserved. Designed for Firefox/Chrome custom search engine templates.

### Method
GET

### Endpoint
`/api/molecules/search`

### Parameters
#### Query Parameters
- **q** (string) - Required - The search term for the molecule.
- **query** (string) - Required - Alias for `q`.
- **search** (string) - Required - Alias for `q`.
- **s** (string) - Required - Alias for `q`.

### Response
- **307 Temporary Redirect** - To the molecule detail page or browse page.

### Error Response
- **400 Bad Request** - If the query parameter is missing or empty.
  - **error** (string) - Description of the error.
```

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

### Standard Git Workflow for Branching and Committing

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Use these standard Git commands if not using Graphite for creating branches, committing changes, and pushing to origin.

```bash
# Create feature branch
git checkout -b feat/your-feature main
```

```bash
# Make changes and commit
git add .
git commit -m "feat: add your feature"
```

```bash
# Push and create PR
git push -u origin feat/your-feature
```

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

### molecules.deleteImage

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Deletes the molecule structure image associated with a molecule. (Note: The source text implies this functionality exists alongside uploadImage but does not provide specific details or a code example.)

```APIDOC
## molecules.deleteImage

### Description
Deletes the molecule structure image associated with a molecule.

### Method
DELETE (inferred)

### Endpoint
/api/molecules/{moleculeId}/image (inferred)

### Parameters
#### Path Parameters
- **moleculeId** (string) - Required - The ID of the molecule whose image should be deleted.

### Response
(No specific success response details provided in the source)

### Error Handling
(No specific error handling details provided in the source)
```

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

### Add or Upgrade UI Dependencies

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Use `bun add` to manage UI package versions, ensuring alignment with the project's supported v3 lines for HeroUI.

```bash
bun add @heroui/react @heroui/styles
```

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

### facilities.create

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Registers a new synchrotron, free electron laser, or lab source facility, with optional instrument details.

```APIDOC
## facilities.create

### Description
Creates a facility with optional instruments. Facility type must be `"SYNCHROTRON"`, `"FREE_ELECTRON_LASER"`, or `"LAB_SOURCE"`.

### Method
`useMutation` from tRPC

### Parameters
- **name** (string) - Required - The name of the facility.
- **city** (string) - Required - The city where the facility is located.
- **country** (string) - Required - The country where the facility is located.
- **facilityType** (string) - Required - The type of facility (`SYNCHROTRON`, `FREE_ELECTRON_LASER`, `LAB_SOURCE`).
- **instruments** (array) - Optional - A list of instruments at the facility.
  - Each instrument object contains: `name` (string), `link` (string | null), `status` (string).

### Response
- The created facility object with nested instruments.
```

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

### Run Database Migrations

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Commands to manage database migrations. Use `db:migrate:run` to apply existing migrations, `db:migrate` to call Prisma directly, or `db:push` for development schema changes. For Supabase-first app roles, consider running `scripts/supabase/app-role-schema.sql` directly.

```bash
bun run db:migrate:run
```

```bash
bun run db:migrate
```

```bash
bun run db:push
```

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

### Run Full Check Suite

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Execute all linting and type checking scripts before committing. This ensures code quality and consistency.

```bash
bun check
```

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

### Authenticate ngrok

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Add your ngrok authtoken to the ngrok configuration to authenticate the service. Obtain your authtoken from the ngrok website.

```bash
ngrok config add-authtoken YOUR_AUTH_TOKEN
```

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

### Run Project Commands with Infisical

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Executes project commands, such as 'bun dev', with secrets automatically injected from Infisical. This avoids the need to manually export secrets to a .env file for runtime.

```bash
infisical run -- bun dev
```

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

### Configure GitHub OAuth Environment Variables

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Set these environment variables to configure the GitHub OAuth client ID and secret for authentication. Ensure the Homepage URL and Callback URL are correctly registered on GitHub.

```bash
GITHUB_CLIENT_ID="Ov23liXXXXXXXXXX"
GITHUB_CLIENT_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

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

### experiments.createWithSpectrum

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Submits a new NEXAFS dataset, including all spectrum points and optional collected-by attribution in a single operation. Requires sample, instrument, edge, and experiment type details.

```APIDOC
## experiments.createWithSpectrum

### Description
Submits a new NEXAFS dataset, including all spectrum points and optional collected-by attribution in a single operation.

### Method
POST (inferred from useMutation)

### Endpoint
/api/experiments/create (inferred)

### Parameters
#### Request Body
- **sampleid** (string) - Required - The ID of the sample.
- **instrumentid** (string) - Required - The ID of the instrument used.
- **edgeid** (string) - Required - The ID of the absorption edge.
- **experimenttype** (string) - Required - The type of experiment (e.g., "TEY").
- **collectedByUserIds** (string[]) - Optional - An array of user IDs who collected the data.
- **spectrumPoints** (array) - Required - An array of spectrum points.
  - **energyev** (number) - Energy in eV.
  - **rawabs** (number) - Raw absorption value.
  - **polardeg** (number) - Polarization angle in degrees.
  - **azimuthdeg** (number) - Azimuth angle in degrees.
- **processMethod** (string) - Optional - The processing method used.
- **preEdgeRange** (number[]) - Optional - The energy range for pre-edge normalization.
- **postEdgeRange** (number[]) - Optional - The energy range for post-edge normalization.

### Request Example
```json
{
  "sampleid": "uuid",
  "instrumentid": "ALS_6.3.1",
  "edgeid": "uuid",
  "experimenttype": "TEY",
  "collectedByUserIds": ["user-uuid"],
  "spectrumPoints": [
    { "energyev": 280.0, "rawabs": 0.012, "polardeg": 54.7, "azimuthdeg": 0 },
    { "energyev": 280.5, "rawabs": 0.015, "polardeg": 54.7, "azimuthdeg": 0 }
  ],
  "processMethod": "STABLE_MONITOR",
  "preEdgeRange": [275.0, 279.5],
  "postEdgeRange": [320.0, 330.0]
}
```

### Response
(No specific success response details provided in the source)
```

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

### Generate New Prisma Migration

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Create a new migration file after modifying `prisma/schema.prisma`. Always review the generated SQL before committing.

```bash
bun run db:generate
```

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

### Create Facility Registration

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Registers a new synchrotron, FEL, or lab source facility. Requires name, city, country, and facility type. Optional instruments can be included.

```typescript
const createFacility = api.facilities.create.useMutation();

await createFacility.mutateAsync({
  name: "Advanced Light Source",
  city: "Berkeley",
  country: "USA",
  facilityType: "SYNCHROTRON",
  instruments: [
    { name: "Beamline 5.3.2.2", link: "https://als.lbl.gov/beamlines/5-3-2/", status: "active" },
    { name: "Beamline 6.3.1",   link: null, status: "active" },
  ],
});
// Returns the created facility with instruments nested
```

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

### Configure ORCID OAuth Environment Variables

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Set these environment variables to configure the ORCID OAuth client ID and secret for authentication. Use `ORCID_USE_SANDBOX=true` for testing with the ORCID sandbox.

```bash
ORCID_CLIENT_ID="APP-XXXXXXXXXXXX"
ORCID_CLIENT_SECRET="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

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

### Browse paginated NEXAFS experiments

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Retrieves paginated and grouped NEXAFS catalog data. Supports filtering by molecule, edge, instrument, and acquisition type. Allows sorting by various keys including 'favorites', 'views', and 'newest'.

```typescript
const { data } = api.experiments.browseList.useQuery({
  limit: 12,
  offset: 0,
  sortBy: "favorites",
  moleculeId: "uuid",              // optional
  edgeId: "uuid",                  // optional
  instrumentId: "instrument-id",   // optional
  experimentType: "TEY",           // optional: ExperimentType enum
});
// data.groups: NexafsBrowseGroup[]
// data.total: number
// data.hasMore: boolean
```

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

### Create NEXAFS experiment with spectrum

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Submits a new NEXAFS experiment, including all spectrum points and optional collected-by attribution, in a single atomic operation. Requires sample, instrument, and edge IDs, along with spectrum data and pre/post edge ranges.

```typescript
const createExp = api.experiments.createWithSpectrum.useMutation();

await createExp.mutateAsync({
  sampleid: "uuid",
  instrumentid: "ALS_6.3.1",
  edgeid: "uuid",
  experimenttype: "TEY",
  collectedByUserIds: ["user-uuid"],
  spectrumPoints: [
    { energyev: 280.0, rawabs: 0.012, polardeg: 54.7, azimuthdeg: 0 },
    { energyev: 280.5, rawabs: 0.015, polardeg: 54.7, azimuthdeg: 0 },
    // ...
  ],
  processMethod: "STABLE_MONITOR",
  preEdgeRange: [275.0, 279.5],
  postEdgeRange: [320.0, 330.0],
});
```

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

### experiments.listEdges

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Retrieves a list of all available absorption edges, sorted with C K and N K edges appearing first, followed by others alphabetically.

```APIDOC
## experiments.listEdges

### Description
Returns all edges sorted with C K, N K, S K first, then remaining edges alphabetically.

### Method
`useQuery` from tRPC

### Response
- **edges** (array) - An array of edge objects.
  - Each edge object contains: `id`, `targetatom`, `corestate`.
```

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

### experiments.browseList

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Provides a paginated and grouped list of NEXAFS experiments. It allows filtering by molecule, edge, instrument, and acquisition type, and sorting by various criteria like favorites, views, and recency.

```APIDOC
## experiments.browseList

### Description
Provides a paginated and grouped list of NEXAFS experiments, allowing filtering and sorting.

### Method
GET (inferred from useQuery)

### Endpoint
/api/experiments/browse/list (inferred)

### Parameters
#### Query Parameters
- **limit** (number) - Optional - The maximum number of results to return per page. Defaults to 12.
- **offset** (number) - Optional - The number of results to skip. Defaults to 0.
- **sortBy** (string) - Optional - The field to sort the results by. Allowed values: "favorites", "views", "geometries", "comments", "name", "newest".
- **moleculeId** (string) - Optional - Filter by molecule ID.
- **edgeId** (string) - Optional - Filter by edge ID.
- **instrumentId** (string) - Optional - Filter by instrument ID.
- **experimentType** (string) - Optional - Filter by experiment type (e.g., "TEY").

### Response
#### Success Response (200)
- **groups** (array) - An array of NEXAFS browse group objects.
- **total** (number) - The total number of experiments available.
- **hasMore** (boolean) - Indicates if there are more results beyond the current page.
```

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

### Molecule Browser Smart Redirect

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Resolves a search term to a molecule detail page or the browse page. Supports query keys like q, query, search, s. Returns a 307 redirect.

```bash
# Direct molecule redirect (exact CAS match)
curl -L "https://xrayatlas.org/api/molecules/search?q=160848-22-6"
# → 307 → /molecules/<uuid>

# Fuzzy redirect to browse when ambiguous
curl -L "https://xrayatlas.org/api/molecules/search?q=fullerene"
# → 307 → /browse/molecules?q=fullerene

# Supported query keys: q, query, search, s
curl -L "https://xrayatlas.org/api/molecules/search?query=PCBM"

# Error response (missing query):
# HTTP 400
# { "error": "A non-empty search string is required.", "example": "/api/molecules/search?q=benzene" }
```

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

### facilities.search

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Searches for facilities by name, returning a list of matching facilities.

```APIDOC
## facilities.search

### Description
Searches for facilities by name.

### Method
`useQuery` from tRPC

### Parameters
- **query** (string) - Required - The search query string.
- **limit** (number) - Optional - The maximum number of facilities to return.

### Response
- An array of facility objects, each containing: `id`, `name`, `city`, `country`, `facilitytype`, `instruments`, `_count`.
```

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

### Parse NEXAFS Filename and Match Instrument

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Parses the six-token underscore-delimited filename convention and attempts to match a known instrument. Includes utilities for normalizing edge and experiment mode.

```typescript
import {
  parseNexafsFilename,
  matchInstrumentIdFromParsedNexafsFilename,
  normalizeEdge,
  normalizeExperimentMode,
} from "~/features/process-nexafs/utils/filenameParser";

const parsed = parseNexafsFilename("C(K)_TEY_ALS_6.3.1_Smith_Sigma.csv");
// {
//   edge: "C(K)",
//   experimentMode: "TEY",
//   facility: "ALS",
//   beamline: "6.3.1",
//   experimenter: "Smith",
//   vendorSlug: "Sigma",
// }

const normalizedEdge = normalizeEdge(parsed.edge);       // "C(K)"
const normalizedMode = normalizeExperimentMode(parsed.experimentMode); // "TOTAL_ELECTRON_YIELD"

const instruments = [
  { id: "als_631", name: "6.3.1", facilityName: "Advanced Light Source" },
];
const instrumentId = matchInstrumentIdFromParsedNexafsFilename(parsed, instruments);
// "als_631"
```

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

### Check and Fix Formatting

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Use these commands to check for Prettier formatting issues and automatically fix them. Ensures consistent code style.

```bash
# Check formatting
bun format:check
```

```bash
# Fix formatting
bun format:write
```

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

### Sync Infisical Secrets

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Pulls the latest secrets from Infisical into the local .env.local file or runs commands with injected secrets without saving them to disk.

```bash
# Pull latest secrets
infisical export --env=dev > .env.local

# Or run with latest secrets without saving to disk
infisical run -- bun dev
```

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

### Branch Naming Convention

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Follow this format for naming branches to ensure consistency across the project.

```git
type/issue-number-brief-description
```

```git
feat/35-user-profile-redesign
```

```git
fix/36-passkey-invalid-character
```

```git
refactor/32-colocation-migration
```

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

### Export Infisical Secrets to .env.local

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Exports development environment secrets from Infisical to a local .env file. This file should not be committed to version control.

```bash
infisical export --env=dev > .env.local
```

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

### List Available Absorption Edges

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Fetches a list of all available absorption edges, sorted with specific edges first, then alphabetically. No parameters required.

```typescript
const { data } = api.experiments.listEdges.useQuery();
// data.edges: [{ id, targetatom: "C", corestate: "K" }, { id, targetatom: "N", ... }, ...]
```

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

### Use Realtime Favorites Hook

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Subscribes to Supabase Realtime channels for the molecule's favorites table and aggregate row. Falls back gracefully on connection errors with bounded exponential backoff.

```typescript
import { useRealtimeFavorites } from "~/hooks/useRealtimeFavorites";

function MoleculeFavoriteButton({ molecule, userId }) {
  const { favoriteCount, userHasFavorited } = useRealtimeFavorites({
    moleculeId: molecule.id,
    initialFavoriteCount: molecule.favoriteCount,
    initialUserHasFavorited: molecule.userHasFavorited,
    userId,
    enabled: true,
  });

  return (
    <button onClick={() => api.molecules.toggleFavorite.mutate({ moleculeId: molecule.id }) }>
      {userHasFavorited ? "♥" : "♡"} {favoriteCount}
    </button>
  );
}
```

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

### Search Facilities by Name

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Performs a search for facilities by name. Requires a query string and an optional limit.

```typescript
const { data } = api.facilities.search.useQuery({ query: "light source", limit: 10 });
// data: [{ id, name, city, country, facilitytype, instruments, _count }]
```

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

### Calculate Bare Atom Absorption Curve

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Computes the theoretical bare-atom mass absorption for a chemical formula by fetching per-element scattering factors from CXRO, interpolating to the spectrum energy grid, and combining by elemental weight fraction. Throws if the formula is unparseable or all element fetches fail.

```typescript
import { calculateBareAtomAbsorption } from "~/features/process-nexafs/utils/bareAtomCalculation";

const spectrumPoints = [
  { energy: 280.0, absorption: 0.012 },
  { energy: 280.5, absorption: 0.015 },
  // ...
];

const bareAtomCurve = await calculateBareAtomAbsorption(
  "C60",          // chemical formula
  spectrumPoints,
);
// bareAtomCurve: [{ energy: 280.0, absorption: 0.00432 }, ...]
// Throws if formula is unparseable or all element fetches fail
```

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

### useRealtimeFavorites

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Subscribes to Supabase Realtime channels for the molecule's favorites table and aggregate row, with graceful fallback on connection errors.

```APIDOC
## useRealtimeFavorites

### Description
Subscribes to Supabase Realtime channels for the molecule's favorites table and aggregate row. Falls back gracefully on connection errors with bounded exponential backoff.

### Parameters
- `moleculeId` (string): The ID of the molecule.
- `initialFavoriteCount` (number): The initial favorite count for the molecule.
- `initialUserHasFavorited` (boolean): The initial state of whether the user has favorited the molecule.
- `userId` (string): The ID of the current user.
- `enabled` (boolean): A flag to enable or disable the subscription.

### Returns
- `favoriteCount` (number): The current total number of favorites.
- `userHasFavorited` (boolean): The current state of whether the user has favorited the molecule.
```

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

### Compute Normalization for Experiment (CXRO)

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Normalizes each polarization geometry group independently using a linear fit against the bare-atom absorption curve. Aggregates a weighted mean scale/offset.

```typescript
import { computeNormalizationForExperiment } from "~/features/process-nexafs/utils/core";

// barePoints from calculateBareAtomAbsorption() below
const result = computeNormalizationForExperiment(
  spectrumPoints,  // multi-geometry SpectrumPoint[]
  barePoints,      // BareAtomPoint[] at the same energies
  5,               // preEdgeCount: number of points at spectrum start to use
  10,              // postEdgeCount: number of points at spectrum end to use
);
// result.normalizedPoints: SpectrumPoint[] (per-geometry normalized)
// result.scale, result.offset: aggregate weighted values
```

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

### Check and Fix Linting

Source: https://github.com/wsu-carbon-lab/xray-atlas/blob/main/CONTRIBUTING.md

Run ESLint to check for code quality issues and fix auto-fixable problems. Enforces project-specific linting rules.

```bash
# Check linting
bun lint
```

```bash
# Fix auto-fixable issues
bun lint:fix
```

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

### molecules.create

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Submits a new molecule to the database. It validates chemical identifiers, deduplicates by IUPAC name, slugifies synonyms, and associates provided tags. Throws CONFLICT if the IUPAC name already exists.

```APIDOC
## molecules.create

### Description
Submits a new molecule to the database. It validates chemical identifiers, deduplicates by IUPAC name, slugifies synonyms, and associates provided tags.

### Method
POST (inferred from useMutation)

### Endpoint
/api/molecules (inferred)

### Parameters
#### Request Body
- **commonName** (string) - Required - The common name of the molecule.
- **iupacName** (string) - Required - The IUPAC name of the molecule.
- **smiles** (string) - Optional - The SMILES string representation of the molecule.
- **inchi** (string) - Optional - The InChI string representation of the molecule.
- **chemicalFormula** (string) - Optional - The chemical formula of the molecule.
- **casNumber** (string) - Optional - The CAS number of the molecule.
- **pubchemCid** (string) - Optional - The PubChem CID of the molecule.
- **synonyms** (string[]) - Optional - An array of synonyms for the molecule.
- **tagIds** (string[]) - Optional - An array of tag IDs to associate with the molecule.

### Request Example
```json
{
  "commonName": "PCBM",
  "iupacName": "[6,6]-Phenyl-C61-butyric acid methyl ester",
  "smiles": "COC(=O)CCC...",
  "inchi": "InChI=1S/C72H14O2/...",
  "chemicalFormula": "C72H14O2",
  "casNumber": "160848-22-6",
  "pubchemCid": "2723997",
  "synonyms": ["PC61BM", "C61-PCBM"],
  "tagIds": ["uuid-of-organic-tag"]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **molecule** (object) - Contains the ID and IUPAC name of the created molecule.
  - **id** (string) - The unique identifier of the molecule.
  - **iupacName** (string) - The IUPAC name of the molecule.
- **updated** (boolean) - Indicates if an existing molecule was updated.

### Error Handling
- **CONFLICT**: Thrown if the IUPAC name already exists.
```

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

### calculateBareAtomAbsorption

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Computes the theoretical bare-atom mass absorption for a chemical formula by fetching per-element scattering factors from CXRO, interpolating to the spectrum energy grid, and combining by elemental weight fraction.

```APIDOC
## calculateBareAtomAbsorption

### Description
Computes the theoretical bare-atom mass absorption for a chemical formula by fetching per-element scattering factors from CXRO, interpolating to the spectrum energy grid, and combining by elemental weight fraction.

### Parameters
- `chemicalFormula` (string): The chemical formula of the molecule (e.g., "C60").
- `spectrumPoints` (SpectrumPoint[]): An array of spectrum points with energy and absorption values.

### Returns
- `bareAtomCurve` (SpectrumPoint[]): An array of points representing the calculated bare-atom absorption curve.

### Throws
- If the chemical formula is unparseable or all element fetches fail.
```

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

### molecules.listTags

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Lists all available tags. Returns an array of tag objects, each containing an ID, name, slug, and color.

```APIDOC
## molecules.listTags

### Description
Lists all available tags.

### Method
GET (inferred from useQuery)

### Endpoint
/api/tags (inferred)

### Parameters
(None)

### Response
#### Success Response (200)
- **tags** (array) - An array of tag objects.
  - **id** (string) - The unique identifier of the tag.
  - **name** (string) - The name of the tag.
  - **slug** (string) - The URL-friendly slug of the tag.
  - **color** (string) - The hex color code associated with the tag.
```

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

### experiments.browseSearch

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Performs a full-text search across the NEXAFS catalog, including experiments related to molecule names, formulas, or synonyms. Supports pagination and sorting.

```APIDOC
## experiments.browseSearch

### Description
Performs a full-text search across the NEXAFS catalog by molecule name, formula, or synonym.

### Method
GET (inferred from useQuery)

### Endpoint
/api/experiments/browse/search (inferred)

### Parameters
#### Query Parameters
- **query** (string) - Required - The search term.
- **limit** (number) - Optional - The maximum number of results to return per page. Defaults to 12.
- **offset** (number) - Optional - The number of results to skip. Defaults to 0.
- **sortBy** (string) - Optional - The field to sort the results by. Allowed values: "favorites", "views", "geometries", "comments", "name", "newest".
- **edgeId** (string) - Optional - Filter by edge ID.

### Response
#### Success Response (200)
- **groups** (array) - An array of NEXAFS browse group objects matching the search query.
- **total** (number) - The total number of experiments found.
- **hasMore** (boolean) - Indicates if there are more results beyond the current page.
```

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

### parseNexafsFilename and matchInstrumentIdFromParsedNexafsFilename

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Parses a NEXAFS filename according to a specific convention and attempts to match it to a known instrument ID.

```APIDOC
## parseNexafsFilename / matchInstrumentIdFromParsedNexafsFilename

### Description
Parses the six-token underscore-delimited filename convention (`edge_mode_facility_beamline_researcher_vendor`) and attempts to match a known instrument.

### `parseNexafsFilename` Parameters
- `filename` (string): The NEXAFS filename to parse (e.g., "C(K)_TEY_ALS_6.3.1_Smith_Sigma.csv").

### `parseNexafsFilename` Returns
- An object with the following properties:
  - `edge` (string): The spectral edge (e.g., "C(K)").
  - `experimentMode` (string): The experimental mode (e.g., "TEY").
  - `facility` (string): The facility where the experiment was conducted (e.g., "ALS").
  - `beamline` (string): The beamline used (e.g., "6.3.1").
  - `experimenter` (string): The researcher's name (e.g., "Smith").
  - `vendorSlug` (string): The vendor slug (e.g., "Sigma").

### `matchInstrumentIdFromParsedNexafsFilename` Parameters
- `parsedFilename` (object): The parsed filename object returned by `parseNexafsFilename`.
- `instruments` (Array): An array of instrument objects, each with `id`, `name`, and `facilityName` properties.

### `matchInstrumentIdFromParsedNexafsFilename` Returns
- `instrumentId` (string | undefined): The ID of the matched instrument, or undefined if no match is found.
```

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

### Fetch Top Favorited Molecules

Source: https://context7.com/wsu-carbon-lab/xray-atlas/llms.txt

Retrieve a limited list of the most popular molecules, ranked by experiment count, favorite count, view count, and creation date.

```typescript
const { data } = api.molecules.getTopFavorited.useQuery({ limit: 4 });
// data.molecules: MoleculeView[]  (pre-sorted by popularity ranking)
```
Tokens:
Raw