@opencloning/utils 1.0.0

package/src/utils/sequenceManipulation.js

@@ -0,0 +1,220 @@
+import { getReverseComplementSequenceAndAnnotations, getReverseComplementSequenceString, getSequenceDataBetweenRange, insertSequenceDataAtPositionOrRange } from '@teselagen/sequence-utils';
+import { fastaToJson } from '@teselagen/bio-parsers';
+import { tidyUpSequenceData } from '@teselagen/sequence-utils';
+
+function getSpacerSequence(spacer, spacerFeatureName = 'spacer') {
+  if (!spacer) {
+    return null;
+  }
+  const spacerSequence = fastaToJson(spacer)[0].parsedSequence;
+  // Add a feature spanning the length of the spacer
+  spacerSequence.features = [{
+    start: 0,
+    end: spacer.length - 1,
+    type: 'misc_feature',
+    name: spacerFeatureName,
+    strand: 1,
+    forward: true,
+  }];
+  return spacerSequence;
+}
+
+export function joinSequencesIntoSingleSequence(sequences, locations, orientations, spacers, circularAssembly, spacerFeatureName = 'spacer') {
+  // Turn the spacers into sequences by parsing them as FASTA with fastaToJson
+  const spacerSequences = spacers.map((spacer) => getSpacerSequence(spacer, spacerFeatureName));
+  // Intercalate the spacers into the sequences
+  const sequences2join = [];
+  const locations2join = [];
+  const orientations2join = [];
+
+  if (!circularAssembly) {
+    const firstSpacer = spacerSequences.shift();
+    if (firstSpacer) {
+      sequences2join.push(firstSpacer);
+      locations2join.push({ start: 0, end: firstSpacer.sequence.length - 1 });
+      orientations2join.push('forward');
+    }
+  }
+
+  for (let i = 0; i < sequences.length; i++) {
+    sequences2join.push(sequences[i]);
+    locations2join.push(locations[i]);
+    orientations2join.push(orientations[i]);
+    if (spacerSequences[i]) {
+      sequences2join.push(spacerSequences[i]);
+      locations2join.push({ start: 0, end: spacerSequences[i].sequence.length - 1 });
+      orientations2join.push('forward');
+    }
+  }
+
+  const fragments = sequences2join.map((sequence, index) => {
+    const seq = getSequenceDataBetweenRange(sequence, locations2join[index]);
+    if (orientations2join[index] === 'reverse') {
+      return getReverseComplementSequenceAndAnnotations(seq);
+    }
+    return seq;
+  });
+  // Concatenate all fragments
+  let outputSequence = fragments[0];
+  for (let i = 1; i < fragments.length; i++) {
+    outputSequence = insertSequenceDataAtPositionOrRange(fragments[i], outputSequence, outputSequence.sequence.length);
+  }
+  return outputSequence;
+}
+
+export function simulateHomologousRecombination(templateSequence, targetSequence, rois, invertFragment, spacers) {
+  const [amplifyRangeSelection, insertionRangeSelection] = rois;
+
+  const amplifyRange = amplifyRangeSelection.selectionLayer;
+
+  const insertionRangeOrPosition = insertionRangeSelection.caretPosition === -1 ? insertionRangeSelection.selectionLayer : insertionRangeSelection.caretPosition;
+
+  let templateFragment = getSequenceDataBetweenRange(templateSequence, amplifyRange);
+  if (invertFragment) {
+    templateFragment = getReverseComplementSequenceAndAnnotations(templateFragment);
+  }
+
+  const spacerSequences = spacers.map(getSpacerSequence);
+
+  let templateWithSpacers = spacerSequences[0] || templateFragment;
+  if (spacerSequences[0]) {
+    templateWithSpacers = insertSequenceDataAtPositionOrRange(templateFragment, templateWithSpacers, templateWithSpacers.sequence.length);
+  }
+  if (spacerSequences[1]) {
+    templateWithSpacers = insertSequenceDataAtPositionOrRange(spacerSequences[1], templateWithSpacers, templateWithSpacers.sequence.length);
+  }
+
+  return insertSequenceDataAtPositionOrRange(templateWithSpacers, targetSequence, insertionRangeOrPosition);
+}
+
+export function findRotation(str1, str2) {
+  const query1 = str1.toUpperCase();
+  const query2 = str2.toUpperCase();
+  // Check if strings are identical
+  if (query1 === query2) return 0;
+  // Check if they're the same length
+  if (query1.length !== query2.length) return -1;
+
+  // Double the first string and search for the second string
+  const doubled = query1 + query1;
+  const rotation = doubled.indexOf(query2);
+  return rotation === -1 ? -1 : rotation;
+}
+
+export function rotateChromatogramData(chromatogramData, rotation) {
+if (rotation === 0) {
+  return {...chromatogramData};
+}
+const {aTrace, baseCalls, basePos, baseTraces, cTrace, gTrace, qualNums, tTrace} = chromatogramData;
+const rotateTrace = rotation * 4;
+return {
+  aTrace: [...aTrace.slice(rotateTrace), ...aTrace.slice(0, rotateTrace)],
+  cTrace: [...cTrace.slice(rotateTrace), ...cTrace.slice(0, rotateTrace)],
+  gTrace: [...gTrace.slice(rotateTrace), ...gTrace.slice(0, rotateTrace)],
+  tTrace: [...tTrace.slice(rotateTrace), ...tTrace.slice(0, rotateTrace)],
+  baseCalls: [...baseCalls.slice(rotation), ...baseCalls.slice(0, rotation)],
+  basePos: [...basePos.slice(rotation), ...basePos.slice(0, rotation)],
+  baseTraces: [...baseTraces.slice(rotation), ...baseTraces.slice(0, rotation)],
+  qualNums: [...qualNums.slice(rotation), ...qualNums.slice(0, rotation)],
+}};
+
+function reverseComplementArray(arr) {
+  return arr.slice().reverse();
+}
+
+export function reverseComplementChromatogramData(chromatogramDataIn) {
+  const chromatogramData = { ...chromatogramDataIn };
+  const complement = { A: 'T', T: 'A', G: 'C', C: 'G', N: 'N' };
+  function reverseComplementSequence(seq) {
+    return seq
+      .map((base) => complement[base] || base).reverse();
+  }
+
+  chromatogramData.aTrace = reverseComplementArray(chromatogramData.aTrace);
+  chromatogramData.tTrace = reverseComplementArray(chromatogramData.tTrace);
+  chromatogramData.gTrace = reverseComplementArray(chromatogramData.gTrace);
+  chromatogramData.cTrace = reverseComplementArray(chromatogramData.cTrace);
+  chromatogramData.basePos = reverseComplementArray(chromatogramData.basePos);
+  chromatogramData.baseCalls = reverseComplementSequence(
+    chromatogramData.baseCalls,
+  );
+
+  chromatogramData.baseTraces = reverseComplementArray(
+    chromatogramData.baseTraces,
+  ).map((traceObj) => ({
+    aTrace: reverseComplementArray(traceObj.aTrace),
+    tTrace: reverseComplementArray(traceObj.tTrace),
+    gTrace: reverseComplementArray(traceObj.gTrace),
+    cTrace: reverseComplementArray(traceObj.cTrace),
+  }));
+  chromatogramData.qualNums = reverseComplementArray(chromatogramData.qualNums);
+
+  return chromatogramData;
+}
+
+export function syncChromatogramDataWithAlignment(chromatogramData, alignmentString) {
+  // If possible, syncs the chromatogram data with the alignment sequence, otherwise
+  // returns the original chromatogram data
+
+  const alignmentSequence = alignmentString.replaceAll('-', '');
+
+  const originalChromatogramData = structuredClone(chromatogramData);
+  let newChromatogramData = originalChromatogramData;
+  const originalSequence = chromatogramData.baseCalls.join('');
+  // Find the rotation of the alignment sequence relative to the original sequence
+  let rotation = findRotation(originalSequence, alignmentSequence);
+  // If the rotation is -1, it may be reverse complemented
+  const reverseComplemented = rotation === -1;;
+  if (reverseComplemented) {
+    rotation = findRotation(originalSequence, getReverseComplementSequenceString(alignmentSequence));
+    newChromatogramData = reverseComplementChromatogramData(newChromatogramData);
+  }
+  if (rotation !== -1) {
+    rotation = reverseComplemented ? originalSequence.length - rotation : rotation;
+    newChromatogramData = rotateChromatogramData(newChromatogramData, rotation);
+
+    return newChromatogramData;
+  }
+  return originalChromatogramData;
+}
+
+export function ebicTemplateAnnotation(templateSequence, roi, {max_inside, max_outside, padding_left, padding_right}) {
+  const leftFeature = {
+    start: roi.start - padding_left,
+    end: roi.start - 1,
+    type: 'misc_feature',
+    name: 'left_homology_arm',
+    strand: 1,
+    forward: true,
+  };
+  const leftMargin = {
+    start: roi.start - max_outside,
+    end: roi.start + max_inside - 1,
+    type: 'misc_feature',
+    name: 'left_margin',
+    strand: null,
+    forward: true,
+  };
+  const rightMargin = {
+    start: roi.end - max_inside,
+    end: roi.end + max_outside - 1,
+    type: 'misc_feature',
+    name: 'right_margin',
+    strand: -1,
+  };
+  const rightFeature = {
+    start: roi.end + 1,
+    end: roi.end + padding_right,
+    type: 'misc_feature',
+    name: 'right_homology_arm',
+    strand: -1,
+  };
+
+  const annotatedSequence = structuredClone(templateSequence);
+  annotatedSequence.features.push(leftFeature);
+  annotatedSequence.features.push(leftMargin);
+  annotatedSequence.features.push(rightMargin);
+  annotatedSequence.features.push(rightFeature);
+
+  return tidyUpSequenceData(annotatedSequence);
+}

package/src/utils/sequenceManipulation.test.js

@@ -0,0 +1,38 @@
+import { syncChromatogramDataWithAlignment } from './sequenceManipulation';
+import teselaJson from '../../../../cypress/test_files/example_chromatogram.json';
+import { getReverseComplementSequenceString } from '@teselagen/sequence-utils';
+
+const exampleChromatogramData = teselaJson.chromatogramData;
+
+describe('syncChromatogramDataWithAlignment', () => {
+
+
+  it('returns original data when sequences match', () => {
+    const result = syncChromatogramDataWithAlignment(exampleChromatogramData, 'TTGAGATC---CTTTTTTT');
+    expect(result).toEqual(exampleChromatogramData);
+  });
+
+  it('handles reverse complemented sequence', () => {
+    const reverseComplementedSequence = getReverseComplementSequenceString('TTGAGATC---CTTTTTTT');
+    const result = syncChromatogramDataWithAlignment(exampleChromatogramData, reverseComplementedSequence);
+    expect(result.baseCalls.join('')).toEqual(getReverseComplementSequenceString('TTGAGATCCTTTTTTT'));
+  });
+
+  it('handles rotated sequence', () => {
+    const result = syncChromatogramDataWithAlignment(exampleChromatogramData, 'CCTTTTTTTTTGAGAT');
+    expect(result.baseCalls.join('')).toEqual('CCTTTTTTTTTGAGAT');
+  });
+
+  it('handles rotated and reverse complemented sequence', () => {
+    const reverseComplementedSequence = getReverseComplementSequenceString('CCTTTTTTTTTGAGAT');
+    const result = syncChromatogramDataWithAlignment(exampleChromatogramData, reverseComplementedSequence);
+    expect(result.baseCalls.join('')).toEqual(getReverseComplementSequenceString('CCTTTTTTTTTGAGAT'));
+  });
+
+
+  it('returns original data when no match found', () => {
+    const result = syncChromatogramDataWithAlignment(exampleChromatogramData, 'GGCC');
+    expect(result).toEqual(exampleChromatogramData);
+  });
+
+});

package/src/utils/sequencingFileExtensions.js

@@ -0,0 +1,8 @@
+export const sequencingFileExtensions = [
+  'ab1',
+  'fa',
+  'fasta',
+  'gb',
+  'gbk',
+  'fastq',
+];

package/src/utils/sourceFunctions.js

@@ -0,0 +1,48 @@
+export function enzymesInRestrictionEnzymeDigestionSource(source) {
+/**
+ * Extracts the enzymes used in a RestrictionEnzymeDigestionSource as an array of strings.
+ */
+  if (source.type !== 'RestrictionEnzymeDigestionSource') {
+    throw new Error('This function only works on RestrictionEnzymeDigestionSource');
+  }
+
+  const output = [];
+  if (source.left_edge) { output.push(source.left_edge.restriction_enzyme); }
+  // add the second one only if it's different
+  if (source.right_edge && (!source.left_edge || source.right_edge.restriction_enzyme !== source.left_edge.restriction_enzyme)) {
+    output.push(source.right_edge.restriction_enzyme);
+  }
+
+  return output;
+}
+
+export const classNameToEndPointMap = {
+  UploadedFileSource: 'uploaded_file',
+  RepositoryIdSource: 'repository_id',
+  AddgeneIdSource: 'repository_id',
+  BenchlingUrlSource: 'repository_id',
+  SnapGenePlasmidSource: 'repository_id',
+  EuroscarfSource: 'repository_id',
+  IGEMSource: 'repository_id',
+  SEVASource: 'repository_id',
+  WekWikGeneIdSource: 'repository_id',
+  OpenDNACollectionsSource: 'repository_id',
+  GenomeCoordinatesSource: 'genome_coordinates',
+  ManuallyTypedSource: 'manually_typed',
+  OligoHybridizationSource: 'oligonucleotide_hybridization',
+  RestrictionEnzymeDigestionSource: 'restriction_enzyme_digestion',
+  PCRSource: 'pcr',
+  PolymeraseExtensionSource: 'polymerase_extension',
+  LigationSource: 'ligation',
+  GibsonAssemblySource: 'gibson_assembly',
+  OverlapExtensionPCRLigationSource: 'gibson_assembly',
+  InFusionSource: 'gibson_assembly',
+  InVivoAssemblySource: 'gibson_assembly',
+  HomologousRecombinationSource: 'homologous_recombination',
+  CRISPRSource: 'crispr',
+  RestrictionAndLigationSource: 'restriction_and_ligation',
+  GatewaySource: 'gateway',
+  AnnotationSource: 'annotate',
+  ReverseComplementSource: 'reverse_complement',
+  CreLoxRecombinationSource: 'cre_lox_recombination',
+};

package/src/utils/thunks.js

@@ -0,0 +1,46 @@
+import { cloneDeep } from 'lodash-es';
+import { base64ToBlob, downloadStateAsJson, downloadStateAsZip, loadFilesToSessionStorage } from './readNwrite';
+import { cloningActions } from '@opencloning/store/cloning';
+import { collectParentSequencesAndSources, getSubState, mergeStates } from './network';
+import { getVerificationFileName } from './readNwrite';
+
+const { setState: setCloningState } = cloningActions;
+
+export const exportSubStateThunk = (fileName, sequenceId, format = 'json') => async (dispatch, getState) => {
+  // Download the subHistory for a given sequence
+  const state = getState();
+  const substate = getSubState(state, sequenceId);
+  if (format === 'json') {
+    downloadStateAsJson({ ...substate, description: '' }, fileName);
+  } else if (format === 'zip') {
+    downloadStateAsZip({ ...substate, description: '' }, fileName);
+  } else {
+    throw new Error(`Invalid format: ${format}`);
+  }
+};
+
+export const CopySequenceThunk = (sequenceId) => async (dispatch, getState) => {
+  const state = getState();
+  const { sequences, sources } = state.cloning;
+  const sequencesToCopy = sequences.filter((e) => e.id === sequenceId);
+  const sourcesToCopy = sources.filter((s) => s.id === sequenceId);
+  const { parentSequences, parentSources } = collectParentSequencesAndSources(sourcesToCopy[0], sources, sequences);
+  sequencesToCopy.push(...parentSequences);
+  sourcesToCopy.push(...parentSources);
+  const sequenceIds = sequencesToCopy.map((e) => e.id);
+  const filesToCopy = state.cloning.files.filter((f) => sequenceIds.includes(f.sequence_id));
+  const newState = cloneDeep({
+    sequences: sequencesToCopy,
+    sources: sourcesToCopy,
+    primers: [],
+    files: filesToCopy,
+  });
+  const files = filesToCopy.map((f) => new File(
+    [base64ToBlob(sessionStorage.getItem(getVerificationFileName(f)))],
+    getVerificationFileName(f),
+    { type: 'application/octet-stream' },
+  ));
+  const { mergedState, idShift } = mergeStates(newState, state.cloning, true);
+  dispatch(setCloningState(mergedState));
+  await loadFilesToSessionStorage(files, idShift);
+};

package/src/utils/transformCoords.js

@@ -0,0 +1,71 @@
+import { parseFeatureLocation } from '@teselagen/bio-parsers';
+import { flipContainedRange, getRangeLength, isRangeWithinRange, translateRange } from '@teselagen/range-utils';
+import { isEqual } from 'lodash-es';
+import { isAssemblyComplete } from '@opencloning/store/cloning_utils';
+
+export default function getTransformCoords(source, parentSequenceData, productLength) {
+  if (!isAssemblyComplete(source)) {
+    return () => null;
+  }
+  const { type: sourceType, input } = source;
+  let fragments = sourceType !== 'PCRSource' ? structuredClone(input) : [structuredClone(input[1])];
+
+  let count = 0;
+  if (sourceType === 'PCRSource') {
+    // Primer is linear sequence, so no need to pass the sequence length
+    const fwdPrimerAnnealingPart = parseFeatureLocation(input[0].right_location, 0, 0, 0, 1, null)[0];
+    count = fwdPrimerAnnealingPart.start;
+  }
+
+  fragments = fragments.map((f) => {
+    // The boolean handles undefined parentSequenceData (for PCR where is [undefined, value, undefined])
+    const sequence = parentSequenceData.find((e) => Boolean(e) && e.id === f.sequence);
+    // If the sequence is not found, it means it's a CRISPR guide / primer
+    if (!sequence) {
+      return null;
+    }
+    const { size } = sequence;
+    const { left_location: left, right_location: right } = f;
+    const leftLocation = left ? parseFeatureLocation(left, 0, 0, 0, 1, size)[0] : null;
+    const rightLocation = right ? parseFeatureLocation(right, 0, 0, 0, 1, size)[0] : null;
+    const leftStart = leftLocation?.start || 0;
+    const rightStart = rightLocation?.start || 0;
+    const rightEnd = rightLocation?.end || size;
+
+    // Handle special case for circular sequences with left_location and right_location being identical (insertion)
+    let rangeLength = isEqual(leftLocation, rightLocation) ? size : getRangeLength({ start: leftStart, end: rightEnd }, size);
+    // Handle special case for circular sequences are excised
+    if (rangeLength > productLength) {
+      rangeLength = productLength;
+    }
+    f.rangeInAssembly = translateRange({ start: 0, end: rangeLength - 1 }, count, productLength);
+    f.size = size;
+    count += getRangeLength({ start: leftStart, end: rightStart - 1 }, size);
+    return f;
+  });
+  fragments = fragments.filter((f) => f !== null);
+  const rangeInParent = (selection, id) => {
+    if (selection.start === -1) {
+      return null;
+    }
+
+    // In insertion assemblies, more than one fragment has the same id,
+    // so we filter instead of find
+    const possibleOut = fragments.filter((f) => f.sequence === id).map((fragment) => {
+      const { rangeInAssembly, left_location: left, reverse_complemented, size } = fragment;
+      const leftLocation = left ? parseFeatureLocation(left, 0, 0, 0, 1, size)[0] : null;
+      const startInParent = leftLocation?.start || 0;
+      if (isRangeWithinRange(selection, rangeInAssembly, productLength)) {
+        const selectionShifted = selection.start <= selection.end ? selection : { start: selection.start, end: selection.end + productLength };
+        const outRange = translateRange(selectionShifted, -rangeInAssembly.start + startInParent, size);
+        if (reverse_complemented) {
+          return flipContainedRange(outRange, { start: 0, end: size - 1 }, size);
+        }
+        return outRange;
+      }
+      return null;
+    });
+    return possibleOut.find((out) => out !== null) || null;
+  };
+  return rangeInParent;
+}

package/src/utils/transformCoords.test.js

@@ -0,0 +1,58 @@
+import getTransformCoords from './transformCoords';
+
+const testData = require('../../../../cypress/test_files/unittests/test_data_transformCoords.json');
+
+const pcrSource = testData.sources.find((s) => s.type === 'PCRSource');
+
+const creLoxData = require('../../../../apps/opencloning/public/examples/cre_lox_recombination.json');
+
+const plasmidExcisionSource = creLoxData.sources.find((s) => s.id === 3);
+const plasmidInsertionSource = creLoxData.sources.find((s) => s.id === 5);
+
+describe('getTransformCoords', () => {
+  it('PCRSource', () => {
+    const parentSequenceData = [
+      { id: 2, size: 23 },
+    ];
+    const productLength = 18;
+    const transformCoords = getTransformCoords(pcrSource, parentSequenceData, productLength);
+    // Normal primer
+    expect(transformCoords({ start: 12, end: 17 }, 2)).toEqual({ start: 8, end: 13 });
+    // Origin-spanning primer
+    expect(transformCoords({ start: 0, end: 6 }, 2)).toEqual({ start: 19, end: 2 });
+  });
+  it('Insertion / circular Assembly', () => {
+    let parentSequenceData = [
+      { id: 1, size: 151 },
+    ];
+    let productLength = 113;
+    let transformCoords = getTransformCoords(plasmidExcisionSource, parentSequenceData, productLength);
+    expect(transformCoords({ start: 1, end: 5 }, 1)).toEqual({ start: 16, end: 20 });
+    expect(transformCoords({ start: 100, end: 0 }, 1)).toEqual({ start: 115, end: 128 });
+
+    parentSequenceData = [
+      { id: 3, size: 113 },
+      { id: 4, size: 38 },
+    ];
+    productLength = 151;
+    transformCoords = getTransformCoords(plasmidInsertionSource, parentSequenceData, productLength);
+    expect(transformCoords({ start: 15, end: 37 }, 3)).toEqual({ start: 0, end: 22 });
+    expect(transformCoords({ start: 2, end: 35 }, 3)).toEqual(null);
+    expect(transformCoords({ start: 0, end: 19 }, 4)).toEqual({ start: 0, end: 19 });
+    expect(transformCoords({ start: 128, end: 150 }, 4)).toEqual({ start: 15, end: 37 });
+    expect(transformCoords({ start: 38, end: 112 }, 3)).toEqual({ start: 23, end: 97 });
+    expect(transformCoords({ start: 38, end: 112 }, 4)).toEqual(null);
+  });
+  it('Edge case', ({ skip }) => {
+    // This is not priority, but it may need fixing. When a circular molecule is excised, the rangeInAssembly
+    // spans the entire product, so any value in isRangeWithinRange(selection, rangeInAssembly, productLength)
+    // is true. When the selection spans the origin, this should not pass, but not sure what else would be affected.
+    skip(true);
+    const parentSequenceData = [
+      { id: 2, size: 151 },
+    ];
+    const productLength = 113;
+    const transformCoords = getTransformCoords(plasmidExcisionSource, parentSequenceData, productLength);
+    expect(transformCoords({ start: 100, end: 20 }, 2)).toEqual(null);
+  });
+});

package/vitest.config.js

@@ -0,0 +1,17 @@
+import { defineConfig } from 'vitest/config';
+import { resolve } from 'path';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: '../../tests/setup.js',
+    include: ['src/**/*.{test,spec}.{js,jsx}'],
+  },
+  resolve: {
+    alias: {
+      '@opencloning/utils': resolve(__dirname, './src/utils'),
+      '@opencloning/store': resolve(__dirname, '../store/src'),
+    },
+  },
+});